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SECTION 7 


By Rich Morin 

A Brief Look at Perl 


a real gem of a scripting language 


Last month's column closed with some short descriptions of 
BSD's scripting Janguages, It offered some opinions, but stopped 
short of recommending any particular language. This month, Til 
get a bit braver, explaining why you might want to use Perl for 
most of your BSDish scripting needs. 

First, however, 1 should caution that Perl is not always the 
appropriate choice. If you’re modifying a system shell script, 
don't try to rewrite it in Perl, just use the language the script is 
written in (typically the Bourne Shell). If you are just 
mechanizing a simple list of commands, Perl is probably overkill, 
hut see below. Finally, if the script has to run early in the startup 
process, the Perl interpreter may not he available. 

Fr)r new, substantial scripts, however, I would strongly 
recommend that you use Perl. Here are some reasons: 

• efficiency - The Perl interpreter, unlike the shells, seldom has to 
start up new proces.ses. This means that substantial Perl scripLs 
will often mn much faster than equivalent shell scripts. 1 found 
this out several years ago, when 1 transliterated several large 
shell scripts to Perl, llie Rin times went down by a factr)r of five! 

• syntax - Most shells have very weak notions of syntax. One 
result of this, in Mac OS X, is that wldte space in file names 
can be interpreted as splitting the names into multiple 
tokens, Perl handles strings in a much more sophi.sticated 
manner, so ii doesn’t get confused. 

• integration - Unlike shell scripts, which may stitch together 
dozens of commands, Perl Ls an integrated language. This 
eliminates a great deal oi hassle and possible confusion, 

• facilities - Perl has powerful data structures, convenient 
control-flow operators, and access to almost any imaginable 
system call. The shells have none of these features. As a 
result, a Perl program can often do things that would be 
essentially impossible in any shell. 

• supfXJn ” Perl has numerous books, a va.st liliraiy^ of 
modules, and a very active user commimity . Most .shells have 
few to none of these resoueces, 

• portability - Perl scripts can be run on essentially any 
modern operating system. With a little forethought, they can 
run unmodified on several different systems. The shells, in 
contrast, only work on BSD and other Unix-like systems. 


Having said all of this, perhaps I should tell you some of the 
had news about Perl: 

• complexity - Perl is a very large language, with some really 
peculiar nooks and crannies. Even if you don’t use all of these 
features, you may well encoimter them in a module or some 
other bit of ccxle you '‘inherit. 

• Informality - Perl’s motto (“There’s More Than One Way To 
Do It” gives fair warning that this isn’t a nice tidy “orthogonal” 
language. In fact, Larry Wall (Perl’s creator) says that Perl is a 
“diagonal” language, cutting acniss die middle often speed 
things up! 

■ mutability - Unlike the shells, Perl is still evolving. Perl 5 has 
(mostly) stabilized, but Perl 6 develf)pment is quite active. So, 
you might need to relearn some things in a few years. 

Show me some code! 

This Ix^ing MacTech, you're probably wondering when 
you’re gr>ing to see some actual Perl code. Well, here’s a short 
Perl script that 1 hacked together to do some backups. It’s not a 
full-featured backup utility, liy any means, but it gets the job 
done (and shows off some Perl language features)... 

*!/iisr/bm/env pt^rl 

• 

* msictec - tirritc backup fiJes, using tar(!). 

# 

^Written by Rich Morin. CFCa.. zmiM 
I 

$date. = ^date ny%ni%d .%H%HU 
chompCSdate): 

@dit ^ (v/Users/rdjti\ 

'/Volumes/Work'); 

for $dir (@dir) ( 

$bac - evt($dir): 

Semd = "nice -10 tar czf $bac $dir": 
printf(">)) %sVn". $cind) ; 
systeiiit^cmd) ; 

] 

1 

sub evt j # convert the directory name 
my ($tmp) = 

$tmp =* *■ s|/| . I&i: 

$tmp ='“ s|\sj_]g: 

return ("/Backups/$date$tnip. tgz:") : 

! 

'rhe first line of any BSD script, as discussed previously, tells 
the system which program should be invoked as the interpreter 


Rich Morin has been using computers since 1970, Unix since 1983, and Mac-based Unix since 1986 (when he helped Apple create A/UX 1.0). When 
he isn't writing this column, Rich runs Prime Time Freeware (www.ptf.com), a publisher of btjoks and CD-ROMs for tlie Free and 0^>en Source software 
communitvt Feel free to write to Rich at rdm@ptf.com. 
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for the following lines. Because I may decide to install a later 
version of the Perl interpreter at some point Ce.g., in 
/usr/local/bin), I don't want to specify a full path name for the Perl 
interpreter. So, 1 tell the system to am /usr/bin/env, letting it find 
and am the appropriate version of Perl. 

The remainder of the script, in any case, is read by the Perl 
interpreter. PerPs syntax and feature set are borrowed from a 
variety of (mostly Unix) languages and tools, including awk, 
Basie-Plus, C, sed, sh, and tr. Tliis makes Perl .seem familiar to 
Unix aficionados, but can cause some culture shock to others. 
Stay calm; it’s not really all that bad! 

Unlike C, Perl has no “block comment.s". So, 1 use a column 
of sharp signs (#) for my header comments. I also like to wTap 
the “main" routine in braces. This causes its contents to he 
indented at the same level as the contents of any sub (routine). 
It also gives me a visual cue that this is a “block” of code. 

1 could have itsked Ped to grab and fonnat the date infonnation 
(and should have, if 1 were Irying for cross-OS ix>rtability), but the 
jnethod alx)ve shows off Ped's ability^ to mn BSD commantLs and 
retrieve tlieir results, Tlie backquotes tell Ped to am the enclased 
command, returning the result as a text string. Tlie fcsult gets put 
into a .scalar variable, $date. llie chomp() function, by tlie way, 
removes tlic trailing newline from date’s output. 

The script then tells Ped to create an array variable named 
@dtr and load it with a list containing two text strings. 1 use 
single quotes to wrap these strings, indicating that 1 don’t want 
Perl to do any variable interpolation (see below) or other tricks. 

Tlie for kxip .sets $dir, succe.s.sively, to each of the values in 
@dtr. Note that the stgil (e.g., $, @ ) Is part of a Perl variable’s name, 
so @dif and $dir are two different variables, Tliis seems a bit weird 
at first, but ends ttp l>eing quite handy as you get used to it. 

The cvl() routine shows off some of Perl’s capabilities and 
peculiarities. First, it grabs (the array of calling parameters) 
and copies the contents into a private list of variables, in this 
case, the list only has one element, but it might well have more. 

Tlie next two lines tell Perl to do global siibstiaitions of 
periods for slashes and underscores for "white space". This gives 
me “flattened’’ names (no directory levels) without any annoying 
spaces, tabs, etc. This is a trivial example of Perfs powerful 
'Tegular expression" capability. Regular expres-sions can be used 
to perform all sorts of magic on text strings. In fact, there is a 
substantial book on regular expressions alone! 

The last line tells Perl to “interpolate'’ the variables $bac and 
$date into a text string. The use of doubie quotes tells Perl to 
look for dollar signs and other “magic” characters, Note that, 
although $tmp i.s a private variable, $date is shared with the main 
routine. Finally, the return is not strictly needed (the value of the 
last expression evaluated in a sub is automatically returned), but 
I think it adds to the clarity of the code. 

Returning to the main routine, we build up a command 
string, print it (ala C), and hand it off to the operating system to 
be run. Look up the man pages for nice and tar to see what their 
roles are in tins script. 

In a script of tliis size, there Isn’t much room to get into 
Perl’s fancier aspects. Next month, Fll give you a more 
substantial taste of its data structures and control flow, as well as 
listing some useful Perl resources. If you can’t wait to get started, 
however, just bop over to www.perl.(orgTorn]... 
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MAC OS X 


By Brent Simmons 

Writing Contextual Menu Plugins for OS X, 
part 1 


Implementing the new COM-compatible 
API 


The API for contextual menu plugins is different in OS X 
than in OS 8/9► It COM-compatible—it's based on Microsoft's 
(Component Object Mexieb 

That should be enough to scare you off, but don't let iL Tire 
good news is you can deal with the COM interface once and re¬ 
use that code. The even better news is that this article will 
provide it for you so you w^on’t liave to write it in the first place. 
After getting the COM parts out of the way, this article will 
show how^ to add a Copy Path menu command to the Finder's 
contextual menu. This command will copy the path of a selected 
file or folder onto the clipboard (a path as in 
/Users/john/myCat.tilT). The second article in this series will go 
Ihrther: it will show how to add submenus, work wiih text 
selections^ and execute Unix commands. 



Figure /. Copy Falb command in Finder's coniextuai menu 


You can download the source and project files for this article 

from 

http://ranchero.com/downloads/mactech/Copy PathPluginSource.sit 

The sample plugin is built with the April 2002 Developer 
Tools version of Prt>ject Builder. 

Before we start coding, let’s get the mile^high view of 
contextual menus on OS X. 

Overview 

The. basic gist of contextual menus is that when you control- 
click on something—some files, a folder, some text—a menu 
appears with commands that do something with what you 
clicked on. 

In other words, contextual menus act on a selection. You 
wouldn't, for example, put the Sleep command in a contextual 
menu, since Sleep doesn't act on a selection. 

Also, you woukln't put an Eject command in a menu that 
appears when text is selected. Though the Eject command acts 
on a selection, it doesn't act on text. An Eject command (or 
similar) should appear only when a removable disk is selected. 

CxmiexLual menu plugins are system-w ide—almost, anyway. 
Not every' app sup]70rts system contextual menus, liuL you’ll find 
plenty tlial do, Encluding Eudora, CodeWarrior IDE, BBEdit, 
Interne! Explorer, and of course the Finder 

Plugins are liiindles; tliey’re CFPlugins. Tliey <;:an be inst^illed at 
"'/Library/Contextual Menu Items/ or at /Iihrviry/C^>ntextual Menu 
Items/ The first loc:ation makes a plugin acceasihle to a specific 
u.ser; tlie second Itxarion makes a plugin accessible to all users. 

Okay. Let's code. 

Implementing the COM IUnknown Interface 

A contextual menLi plugin has three things it must do: add 
menu items when requested, run a chosen menu command, and 
satisfy the requirements of the COM-compatible API. 

Well start with the COM stuff, because it's not utterly 
thrilling—and, gotten out of the way once means it’s out of tiie 
way forever, In Pact, if you Ye in a hurry you can skip down to 


Brent Simmons is a Seartk-based independent Mac OS X developer and writer, a fan of both Cxjcoa and Carbon, Ke runs a Mac developer news 
weblog at rancliero.com; he can be contacted at brent@ranchero.a>m. 
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the UUIDs section below. 

IUnknown 

Think of COM as a framework for object-oriented plugins. 
Every plugin must implement the IUnknown interface. 
IUnknown is the base class; it implements interface querying 
and reference counting. 

Specifically it implements three functions: addRef, which 
increments the reference count; release, which decrements the 
reference count and releases the object if the count goes to zero; 
and querylnterface, which is called to determine if a plugin 
implements a given interface. 

Cocoa developers especially are familiar with reference 
counting. Each time a COM object is retained its reference count 
is incremented. When ids released, the reference count is 
decremented. When it goes to zero the object is disposed. 

If you're not familiar with reference counting, you can think of 
it as a “friends” counter. Each time you get an addRef call, it's like 
.someone ringing you up and saying, hey, I'm your friend Each time 
you gel a release call, it's like someone ringing you up and saying, 
hey, Vm no longer your friend. You keep a count of how many 
friends you have. When the count gtxfs to zero you may as well not 
exist anymore. (It's a good thing people aren’t COM objects.) 

Incrementing the reference count 

addRef, the first of the required IUnknown interface 
functions, is called to increment the reference count: 

Listing 1: incrementing the reference count __ 

addRef 

static ULONG addRef (void ^pluginlnstance) 

[ 

tyPlugin 'instance = (tyPlugin*) pluginInstance: 

{'instance).refCount +" It 
re turn (('instan c e).refC nunt ); 

f 

[t gets a pointer to an instance of the plugin and bumps 
refCoimt. (Note that though it returns the reference count, this is 
just a convention, not something to be relied on.) 
tyPlugin is a struct defined in CopyPathPlugin.h: 

typedef struct tyPlugin I 

Cont extualMenuInte rfaceStruct * cininterface; 

CFtJUIORef factory Id; 

UInt32 refCount; 

I tyPlugin: 

The first element of the tyPlugin struct is a pointer to a 
struct that lays out the functions implemented by the plugin, 
factory Id is the unique ID of the plugin. refCount is the current 
reference count. 

ContextualMenuInterfaceStruct, also defined in 
CopyPathPJugin.h, looks like this: 

static ContextualMenuInterfaceStruct interfaceTable = ( 

NULL, 

querylnterface* 

addRef. 


release, 
examineContext * 
handleSelection. 
postMenuCleanup 
1; 

The first item is some necessary padding. Tlie next tliree 
functions—querylnterface, addRef, and release—are required by 
the IUnknown interface. The final three functions— 
examineOjntext, handlefielection, and postMenuCleanup^are 
required by tlie contextual menus plugin interface. 

Decrementing the reference count 

release, the second of the required IUnknown interface 
functions, is called to decrement the reference count. When the 
reference count goes to zero, the instance is disposed. 

Listing 2: decrementing the reference count _ 

release 

static ULQNG release {void 'plugiQlnstance) 

( 

tyPlugin 'instance ^ [tyPlugin') plugininstance: 

{'instance).refCount 1; 

if (('instance).refCount = 0) ( 
deallocatelnstance (instance); 
return {0}; 

) 

return [('instance).refCount); 

1 

Tlie important part is where it checks if refCount has gone 
to zero and in tliat case calls deallocatelnstancc. 

listing 3: deallocating an instance of the plugin_ 

doUocatdnsunce 

static void deallocatelnstance (tyPlugin 'plugininstance) 

I 

CFUUIDRef factoryId = ('pluginlnfltance).factoryId: 
free {plugininstance); 
if (factoryld) { 

CFFluglnRemovelnstanceForFactory (factoryld): 

CFRelease [factoryld); 

I 

1 

The instance Is passed to free wliich deallocates the 
memory. Then the instance is disassociated from its factory ID 
and the factory ID reference is released. 

Allocating a new instance 

How are instances allocated in the first place? The system 
calls the factory function pluginFactory to create new instances 
of the plugin objea. It knows to call pluginFactory because in 
the Application Settings in Project Builder we've specified 
pluginFactory as the name of the factory method. 

Choose Edit Active Taiget from the Project menu; click on the 
Bundle Settings tab; click on the Expert button (in the upper right 
of the window). Expand the CFPluginFactories line and underneath 
you'll see die UUID of this plugin with a value of pluginFactory. 
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f Iere'.s pluginFactory itself: 

Listing 4; creating a n^ instance of the plugin 

pluginFactory 

void* pIuginFactoiry (CFAllocatorRef allocator* 

CFtlUlDRef typeld) 

( 

^pragma unused (allocator) 

if (CFEqual (typeld* kContextualHenuTypelD)) 

return (allocatelnstance (kCMPluglaFactoryldJ}; 
return [NULL): 

] 

First it does a ^nity-check ( via CFEqual) that what's wanted 
is a contextual menu plugin, then it calls ahocatelnstance to 
actually allocate a new instance. 

Listing 5: allocating a new instance of the plugin 

allocaiclDstance 

static tyPlugin* sllocatelnstance [CFUUIDRef factoryld) 

[ 

tyPlugin *newlastance: 

nevlnstauce = (tyPlugin*) malloc (slzeof {tyPlugin)): 

(*newInstance).cmlnterface ^ ilnterfaceTable: 

(*newlnstance).factoryld = CFRetain (factoryld); 

CFPlugInAddInstanceForFactory (factoryld): 

(*newlnstance).refCount = 1: 

return [newlnstance); 

1 

Malloc allocates die memory for a new instance, then tlie 
elements of the staict are filled in. cmlnterface geLs a pointer to 
the interface table (a ContextualMenulntedaceStiuet). The factory 
ID is set and retained via CFRetain. The instance is associated widi 
tliis factory 11) via CFl^luglnAddtastanceForFaaory. refQiunt is set 
to 1 and the instance is returned. 

query Interface 

querylnierface, the third and last of the required RJnknown 
interface functions, is called to check to see if a given plugin 
implements a given interface. 

Listing 6: handling an interface query 

query tnicrfiicc 

static HRESULT queryInterface (void* pluginInstance* 

REFIID ild, LPVOID* ppv) 

I 

if (isGoodlnterface (ild)} { 
addRef (plugininstance): 

‘ppv ” plugininstance; 
return £S_0K): 

I 

*ppv » NULL; 

return [E_NOINTERFACE); 

J 

If the interface is one that this plugin implements, then the 
reference count is incremented (via addReO and a pointer to the 
plugin instance is returned. Otherwise an error code 
(E.NOlN'rERFACE) is returned* 

isGoodInterface checks to see tliat tlie requested interface is 
either IUnknown or the contextual menu plugin interface. 


Listing 7: determining if a requested interface is 
implemented by this plugin 

IsGoodlnteriiice 

static Boolean isGoodInterface (REFIID iid) 

I 

CFtnilDRef iuterfaceld - 

CFUUIDGreateFroniOUrDBytes (NULL, ild): 

Boolean flGoodlnterface “ false; 

if (CFEqual (interfaceld. kContextualMenuInterfacerD)) 
flGoodlnterface = true; 
if {GFEqual (interfaceld. lUnknovnUUID)) 
flGoodlnterface ^ true; 

CFReLease (interfaceld): 
return (flGoodlnterface): 

I 

It creates a CFLIUIDRef tliai can lx? compared to tlie contextual 
menu interface 11) and tlie IUnknown ID. If it imtches either 
interface ID, tiien it's an interface tliiit this plugin implements. 
i.sGcxxlInterface returns true if there’s a match, taLse odierwise. 

LTUIDs 

This is the only COM thing you have U> re-do for each plugin 
you create. Luckily, it’s a piece of cake, just slightly tedious. 

A UUID is a universally unique identifier that identifies your 
plugin. In this sample it appears in CopyParliPlugin.h as the 
following un-aesthetic lines: 

/*Tht* unique tO for this plugin: 

(:EliFF4624(:32-l ID6-AI St:^XH(JE4Sy IB5CV 

#define kCMPlugInFactoryld CCFUUIDGetConstantUUIDWithBytes \ 
(NULL. OjeCE. DxEF, OxFA. 0 x 62 . 0 x 6 G. 0 x 32 , 0 x 11 . 0 xD 6 . \ 

OxAl. 0 x5C. 0x00. 0x50. OxEA. 0x 59. OxlB. 0x30) 

To generate a new^ UUID, launch TerminaLapp, and on the 
command line type uuidgen and hit Return. Underneadi will 
appear a new UUID, (See Figure 2.) 



Figure 2, Generating a UUID via the command lim 

When you go to create your own plugins, copy the UUID 
generated by uuidgen into your code as in the sample. Then 
do the tedious bit of copy-and-paste needed to make it look 
like die above. 
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Then choose Edit Active Target from the Project menu; click 
the Bundle Settings tab; click the Expert button. Your UUID 
should appear in two places (as in tliis sample): under 
CFPluglnFactories and under CFPluglnTypes. (See Figure 3 ) 



Figure 3 Bundle settings 


Enough COM. Let’s do the fun part, the contextual 
menus interface. 

Contextual Menus Interface 
Contextual menu plugins must implement three functions 
beyond the three required IUnknown interface functions. 

examineContext is called to give the chance for the plugin 
to add commands to the menu that’s being built. The plugin can 
see what the current context is, and decide what commands to 
add or not add. 

handleSelection is c’atled to actually run the command the 
user chose. 

posiMenuCleanup is called afterward in case tlie plugin has 
any cleanup to do. 

examineContext 

You don't own the contextual menu, you just get the chance 
to add one or more commands. It’s a shared menu: the system 
may add commands and other plugins may add commands. 

This sample plugin will add a Copy Padi command when a 
file or folder is selected in the Finder. examineConrext is the first 
of the required contextual menus interface functions. 

Listing 8: determining if a file object is selected _ 

_^examineComext 

statlt OSStatus examineContext (void ''piuginlnstaTice, 
const AEDesc * contexts AEDescList '^cotmnandLlst) 
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if (getFileObject (context, nil)) 

return (addConnnandToHenu (cocmtandList)) J 

if (getFileObjettFromList (context, nil)) 
return (addCamiaandToMenu (commandList)); 

return (noErr)■ 

) 

Here’s an important point: tliough we said above that we 
want this command to appear only in die Finder, in fact well do 
something smarter. Let’s not care if it it’s the Finder or not, let's 
care only that ids a file or folder object that's selected. 

Tliat way, if someone writes a finder replacement tiiat 
supports system contextual menus, this plugin will work tliere too. 

A general rule of thumb is dial the important part of the 
context is the type or types of objects selected. The 
application is of lesser importance, when ids even important 
at all. In this sample we don't care if iVs Apple’s Finder, John 
Doe's cool replacement Finder, or any other app that presents 
file objects, 

context is an Apple event descriptor describing the objeti or 
objects selected* What we want to know is if it’s a file or h)lder 
selected. To do dial we see if the object eitlier is or can be coerced 
to a descriptor of typeAiias (which points to a file or folder). 

So examineContext calls getFileObject which returns tnie if 
context is already of typeAiias or can be coerced to typeAiias. (It 
may be of typeFSS, for instance.) 

If getFileObject returns false, then examineContext calls 
getFtleObjectFromList. [f context is an AEDescList, dien it checks 
to see if the first item in the list is of typeAiias or can be coerced 
to typeAiias. The reason we do tlus is bec'ause in testing we 
discovered diat context is always an AEDescList when selecting 
even just one file or folder in the Finder. We could perhaps have 
gotten away with assuming that that would always be true, and 
skipped the call to getFileObject, but then a future version of the 
Finder might break our plugin. (Or die plugin might not work 
with other apps w^here context isn’t always an AEDe.sdist*) 

getFileObject 

This function checks to see if a descriptor is of typeAiias or 
can be coerced to typeAiias. 

Listing 9: getti ng a file obje^. from the context descriptor 

gclFilcObjm 

static Boolean getFileObject (const AEDesc *desc* 

ASDesc VresultDesc) 

[ 

AEDesc tempDesc = ItypeNull, NULL}: 

Boolean flFile - false; 

OSErr err ” noErr: 

if {C*desc).descriptorType = typeAiias) t 
if [reaultDesc 1= nil) 

return. (AEDuplicateDesc (desc, resuItDesc) noErr): 
elee 

return (true); 

} 

err = AECoerceDesc (desc, typeAiias, StempDesc): 

if ((err = noErr) 

(tempDesc.descriptorType = typeAiias)) [ 
flFile - true: 

if [resultDesc != till) 


flFile =(AEDuplicateDesc (^tempDesc, resultDesc) 
= noErr): 

I 

AEDisposeDesc (^tempDeec); 
return (fLFlle): 


If context is already of typeAiias, then we know it's a file or 
folder, and the function returns true. The function checks 
(*desc).descriptorType to determine the type of die context 
descriptor. 

If context can be coerced to typeAiias (via AECoerceDesc), 
dien again the funedon returns true. Otherwise it returns false. 

Note that this function will make a copy of context (via 
AEDuplicateDesc) in resultDesc if the caller wants. Tliis will be 
used later when the plugin ls called to run our menu cemmand 
(via handleSelection). 


getFiltfObjectFromlist 

This functitjn gets a file object from a list (an AEDescList). 

listin g l(k g etttog a file object from a n AEDesclist_ 

gLiFilcdbjectFromList 

static Boolean getFileObjectFromList (const AEDesc *desc, 

AEDesc ‘resultDesc) 

I 

Boolean flFile = false: 
long numltems " 0: 

OSErr err = noErr: 

AEKeyword keyvord: 

AEDesc tenipDesc ItypeNull, NULL): 

if C{‘desc).descriptorType S” typeAEList) 
return (false): 

err “ AKConnrlteiiis {desc, &numlterns): 
require_noerr (err, getFileObjectFrcniiList_fall): 

if (numlterns “1) [ 

err = AEGetNthDesc (desc, 1, typeWlldCard, 

^keyword, itempDesc); 
if (err = noErr) ( 

flFile = getFileObject (StempDesc, nil]: 

if ((flFile) hh (resultDesc t= nil)) 

AEDuplicateDesc (SteBipDesc, resultDesc) : 
AEDlsposeDesc (fiiteupDesc): 

1 

} 

get F i leOb j e c t F roiaLi st_f ai 1; 
return (flFile); 

] 


First it makes sure dial context is in fact an AEDescList. 
Then it counts die number of items in the list via AECountltems. 
If die number of items is one, then it gets the first item 
(AEGelNthDesc), then emails getFileObject to see if that first object 
is of typeAiias or can be coerced to typeAiias. 

As with getFileObject, this function will return a copy of die 
file object in resultDesc as a typeAiias descriptor if the caller 
wishes. But for examjneContext we don’t want a copy, we just 
want to know if it’s a file object or not. 

Back to examineContext: if either getFileObject or 
getFileObjectFromList return true, then it calls 
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addCommandToMenu to add the Copy Path command to the 
contextual menu. 

Adding a command 

The contextual menu being built is passed to 
examineContext as an AEDescList. To add a command to the 
menu, addMenuCominand creates an AERecord and adds the 
command string and command ID. Then it adds the record to 
the end of commandDst. 


Listing 11: adding the Copy Path command to the 

contextual menu ___ 

sddCommajidToMcnu 

static OSStatUs addCommandToMenu (AEDescList ’coimiiandLiat} 

f 

AERecord ccumnand = ttypeNull, NULL]; 

Str255 commandstring = copyPathCommand: 

OSErr eir ■ noErr; 

Sint32 comandld ^ 2000 j: 

err = AECreateLlst Q. true. &coinmand)r 

reqiilre_noerr (err, addCommandToHenu_coinplete_fail): 

err = AEPutKeyPtr (Sicomitand, keyAENaroe, typeChar. 

^coramandStritig [1], comraandStrlng [0]); 
cequire_noerr (err, addCoiiimandTciHenu_fail]: 

err = AEPutKeyPtr (^command, 'cmed', 

typeLonglnteger. & command Id, siasnof (coiMiandId)); 
r e quir e_noe r r (err, ad d CommandToMen u_ f ai1): 

/*{} mifans add m md of lisi,V 

err “ AEPutLEsn (ccmnnandList* 0* ficomniand): 

addCommandToMenu_failj 
AEDispoaeOesc (^connnand); 
ad d ConmiandToMe nu_ccimpl e t e_f ai 1: 
return (err): 

J 

Tlie command is created via AECreateList. AEPutKeyPtr is 
used to add the text of the command and its command ID. (This 
sample dtK^sn't actually use the command ID, since there's jusi 
one menu ccjmmand—but it' you have more than one command 
the command ID is quite useful.) 

Finally the command record is added to the end of the 
command list via AEPutDcsc. 

After cleaning up, addCommandToMentt reairns, then 
examineOmtext returns. Then we move on to implementing 
handleSelection. 

handleSelection 

This function, the second function required by the 
contextual menu interface, is called to run a contextual menu 
t'ommand. In this sample we run the Copy Path command. Our 
version of handleSelection looks like this: 


Listing 12: handling UieCopy Path mmmand 

handlrScl(;r[i{>n 

static OSStatiiE handleSelection (void ’pluglnlnstance. 

AEDesc *conteKt, SInt32 conraiandid) 


AEDesc aliasDesc = itypeNull. MULL I: 
char path IMAXPATHLEN]: 

OSErr err = noErr; 

If (IgetAliasDesc (context. &aliaaDesc)} 
return (noErr): 

if (getPathStringFroniAliaa (&aliasDesc, path)) 
writePathToC1ipboa rd (path): 

AEDigposeDesc (ialiasDesc): 
return ferr): 

I 

It takes a pointer lo the plugin instance, a pointer to the 
context (the same coniext that examineContext gets, a 
description of the selected objeaCs)), and the command ID of 
the menu command that was chosen. 

Just as in examineContext, we want to gel a descriptor of 
typeAIias from context. So getAliasDesc is called to gel a 
typeAiias descriptor. If it fails, the plugin does nothing. 

Once it has tlie descriptor, it aills geiPathSiringFromAlias to 
get die padi to the file object as a C string. Then it calls 
writePadiToCliplxjard to write tlie path string to the clipboard. 
After cleaning up it returns. 

getAhasE^ese 

Backing up.,, here's getAliasDesc: 

Listing 13: getting a typeAiias descriptor 

gciAiiasDesc 

static Boolean getAliasDesc [const AEDesc *desc. 

AEDesc *resultDesc) 

I 

if (gelFileObject [desc, resultDesc)) 
return (true): 

return (getFileObjectFroinList (desc. resultUeac)): 

1 

It calls getFilcObject and getFileObjectFromList, which are the 
.same hmetions we used in exiimineContexl to determine if a file 
object was selected. The difference here Is that the second 
parameter to tliese functions is nt>i null, it’s a pointer to a 
descriptor that should become a typeAiias descriptor —ii file object. 

getPathStringFromAlias 

handleSelection then calls getPathSiringFroniAlias: 

Listing 14: getting a path string from a typeAiias 
descriptor _ 

grt PiithSt ringFromAlias 

statio Boolean getPathStringFromAliae (const AEDesc *desc, 
char ‘path) 

[ 

FSRef fileRof: 

Size dataSlze ^ AEGetDescDataSize (desc); 

AiiasHandle aliasRef; 

Boolean flChanged = false: 

OSEri: err = noErr: 

aliasRef “ (AliasHandlG) NewHandle (dataSizc); 

If (allasRef = nil) 
return (falee): 
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err = AEGetDescData Cdesc, 'aliasRef, dataSize]; 
require_tioerr (err. getFileObjectFrotEiAllaE_fall); 

err = FSResolveAlias (NULL, aliasRef, 

&fileRef. &flCbanged); 

requlre_noerr (err. getFile0b5ectFroinAllas_fail)■ 

err = FSRefMakePatb (SflleRef. CUIutS*) path* 

MAXPATHLEN); 

getFileObjectFromAlias^fail: 

DiaposeBandle {(Handle) aliasRef); 
return (err = noErr); 

I 

It allocates a new AliasHandle via NewHandle, then gets iLs 
data by c'alling AEGetDescData to get it from the typeAlias 
descriptor. 

Then it gets an FSRef from the AliasHandle by calling 
FSResolveAlias. 

Then it gets a path string from the FSRef by calling 
FSRefMakePath. (Note: MAXPATHLEN is defined in sys/param h, 
wliich is included by CopyPathPlugin.h.) 

It returns after cleaning up. 

writePathToClipboard 

Finally handleSelection calls wriiePatliToClipboard which 
writes the patli suing to the clipboard. 

Listing 15: writing text to the clipboard 

WritePathToClipboard 

static void writePathToClipboard (char 'path) 

[ 

ScrapRef scrap; 

ClearCurrentScrap (); 

GetCurrentScrap {&scrap); 

PutScrapFiavor (scrap. kScrapFlavorTypeText. 
kScrapFlavorMaskNone» strlen (path), 

(const void*) path): 

I 


It clears die current scrap (cliplxiard), gets a reference to 
the current scrap, then writes die string as text to the scrap via 
PutScrapFlavor. Simple. 

That’s it for implementing handleSelection. 

postMennCleanu p 

This function is the third and last function required by the 
contextual menu interface. If the plugin had any cleanup to do 
after running the command, this would be Uie place to do it. Bui 
since Lhere\s no cleanup to do (in Uiis sample), 
postMenuCleanup is a no-op: 

Listing 16: cleaning up _ 

postMcnuCJcaiiup 

static void postMenuCleanup (void *pluginlrjstance) 

t 

/*Tliis plugin Im no de^up to do.*/ 

1 


Testing and debugging plugins 
After building your plugin, youll find it in the build 


directory in the projea directory. Copy it to '-/Library/Contexiual 
Menu Items/. You may need to create the Contextual Menu 
Items folder if it doesn’t already exist. 

If youYe replacing a plugin that's already installed, first trash 
the old version, then copy the new version into the Contextual 
Menu Items folder 

YouT need to quit and restart the Finder before it will see 
the new version of the plugin. What I do is put an AppleScript 
script in my dock that looks like this: 

tell application “Finder" 
quit 

end tell 

OS X is just a bit unpredictable when it mns this script. 
Sometimes the Finder quits twice. Sometimes the Finder restarts, 
sometimes not. No harm is apparent. If the Finder doesn’t 
restart, click the Mac smiley face icon in the Dock and the 
Finder will launch. 

If you'd ratiier, you can log out tlien log back in instead, 
which also restarts the Finder. 

To test this plugin, install it as above, then control-click (or 
right-click if you iiave a two-button mouse) on one file or folder 
in the Finder. You should see a Copy Path command in the menu 
that appears. Choose the command, then choase Show Clipboard 
from the Finder’s Edit menu. The clipboard contents should be 
text, the path to the object you clicked on. Try doing a paste in 
anotlier app just to make sure everything works as expeaed. 

Tip: for debugging plugins I use printf calls. The output 
appears in Console.app, which you can find in the 
/Applications/Lltilities/ directory. 

Conclusion 

As you've seen, implementing contextual menu plugins in 
OS X IS not terril^ly difficult, it's just that the COM-compatible 
interface is not obvious. Given sample code and an 
understanding of how tlie COM interface works, you can 
concentrate on tlie ctxle that’s unique to your plugin. 

Coming in part two 

In the next article well go farther, well show how to 
build a submenu, how to send an update event to the Finder, 
how to handle selected text (in apps such as BBEdit and 
Internet Explorer), and how to call a Unix command from a 
menu command. 

References 

• Apple sample code: 

http://developer.apple.com/sanriplecode/Sample_Code/HumanJnterface 
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QUICKTIME 
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A Bug’s Life 


Retrieving Errors in QuickTime 
Applications 


iNTRODUCnON 

I'ermites happen. So do errors in QuickTime-savvy 
applications — often for reasons other than mere sloppy 
programming. Network connections can fail in the middle of 
downloading a movie file or otlier data. System resources 
(memory, disk space, and so forth) am get depleted while an 
application runs. Components necessary* for the playback of 
some media data might not be available on a particular machine. 
In short, lots of unpredictable occurrences can lead to tlie failure 
of QuickTime functions. How you deal widi those failures is up 
to you. You might tlirow an exception, which (hopefully) is 
caught by an exception handler. Or you might just return an 
error code to your caller and expect it to handle the error 
gracefully. This is all part of the theory and practice of error 
handling, which is often the subject of heated debates among 
programmers. But before you even begin to handle an error, you 
first need to discover that it occurred in the first place. Tliat’s tlie 
subject of this article: how^ to determine dial a QuickTime 
function has failed to do what you wanted it to do. 

At first glance, this might seem like a fairly trivial topic. After 
all, many QuickTime functions return a result code that indicates 
the success or failure of the operation. But in fact things are not 
always that simple. For starters, not all QuickTime functions 
return a result code directly to the cailen Many of them, 
particularly Movie Toolbox calls, return a result code only 
indirectly, and we need to do a little work to retrieve that result 
code. We'll begiii tliis article by looking at how to do that. Also, 
It’s easy to misinterpret some of these result codes, so well 
investigate some of tlie pitfalls lurking here. Toward the end of 
the article, we'll take a look at a bug in our sample applications 
that I inadvertently added a few niondis ago. 

Error-Reporting Functions 

A large ntimber of QuickTime functions return a result code 
directly to the caller as dieir function result. For instance, the 


EnlerMovies function is declared essentially like this: 

OSErr EnterHovles [void]: 

If a call to EnterMovies fails, QuickTime tells us so by returning 
a non-zero result code. The main reason that EnterMovies can fail 
is insufficient memory available for QuickTime to do the 
necessary initialization, so the result code is very likely to be 
memFuilErr. No matter what the error here, however, our sample 
applications all quit pretty much immediately after they gel one, 
first informing the user of the error. Listing 1 shows a portion of 
our application start-up code on the Macintosh. 


myErr = EnterMovies(); 
if (ciyErr 1= noErr) f 

QTFca]ne_ShowWarning{"\pCi:fuld not initialize QuickTime. 

Exiting.". iiiyErr); 

ExitToShell0; 

I 


main 


And listing 2 shows the corresponding code in our Windows 
applications. 


listing 2:: 


myErr = EnterMovies(): 
if CmyErr [= noErr) ( 

MessageBos(HULL. "Could not initialize QuickTime. 

Exiting,", gAppName, HB,OK | MB.APPLMOBAL): 
return(O): 

I 


WinMain 


But a significant number of QuickTime functions do not 
return an error code as their ftinotion result. A gtxid example Is 
StaitMovie, which is declared like this: 

void StartMovie (Movie theMovie); 

As you can see, StartMovie returns no function result at all. Some 
other functions do return function results but they are not of type 
OSErr. An example here is GetMo vie Active, which returns a 
result of type Boolean: 

Boolean GetHovieActive (Movie theMovie); 


Tim Monroe in a member of tlie QuickTime engineering team. You can contact him at monroe@apple.com. The views expressed here are not 
necessarily shared by his employer. 
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To handle cases like these, QuickTime provides a set of 
error* re porting functions. Let's see how these work. 

Getting the Current Error 

We can use the Movie TrX)lbox function GetMoviesEiror to 
retrieve the current error mine (or curreut error), which is the 
result code of the most recently executed QuickTime function- 
GetMoviesEiror is declared like this: 

OSErr GetMoviesError (void): 

We can use GetMoviesEiror to get tlie result code for those 
funaions that do not return one as their function result. 
(GetMoviesEiror also returns the result code tor functions dial do 
return an OSErr, but it’s pretty much redundant in those cases.) 
Here's a typical use of GetMoviesEiror: 

mylrack = NewMovl€Track(inyMQviet rayWidth^ my Height, 0) ; 
myEtt = GetMoviesError() ; 
if (myErr 1^ noErr] 
goto bail; 

We could just as easily have checked to .see whether mylrack is 
equal to NULL after the call to NewMovieTrack, but calling 
GetMoviesEiror gives us a result code that we can rerurn to our 
caller, if so desired- 

It’s worth noting that GeiMoviesError (and 
GetMoviesStickyError, which we'll consider in a moment) are 
global to an application and are not thread-specific. This means 
that an error that occurs in one thread can be reported to 
another tliread. (Just sometliing to keep in mind if you are 
writing multi-threaded application.s.) 

Getting the Sticky Error 

QuickTime also maintains an error value called the sticin- 
eiror mlue (or sticky eiror), which is the first non-zero result 
code of a Movie Toolbox function that was generated since the 
last time the sticky error w^as cleared- We retrieve the sticky error 
value by calling GetMoviesStickyError and we clear the sticky 
error by calling ClearMoviesStickyError. Here are the function 
prototypes: 

OSErr GetMoviesStickyError (void): 
void ClearMoviesStickyError (void); 

When our application first starts up, the sticky error Ls 0. If 
all our Movie Toolbox function calls succeed, the sticky error 
remains set to 0. But as soon as any Movie Toolbox function 
encounters an error, die appropriate error value is copied into 
the sticky error value. We can call GetMoviesStickyError at any 
time to retrieve the sticky error value. This value does not 
change, even if subsequent Movie Toolbox calls fail, until we 
explicitly reset it to 0 by calling ClearMoviesStickyError- 

The sticky error value is useful when we want to execute a 
series of Movie Toolbox functions but don’t particularly want to 
check for errors after each Movie Toolbox call- Listing 3 shows 
a situation in which GetMoviesStickyError might be used. The 


function VKObject_importVideoTrack copies a video track from 
one movie (the source) into a second movie (die destination). 

Listing 3: Importing a video track from one movie into 

another _ _ 

VRObjeci^lmportVideoLmck 

OSErr VRObject_IiiiportVldeaTrack (Movie tLeSrcMovie, 

Movie theDstHovie, Track ‘^thelmageTrack) 


Track 

myS rcTrack * 

NULL 

Media 

mySrcHedia = 

NULL 

Track 

myDstTrack = 

NULL 

Media 

myDstMedia " 

NULL 

Fixed 

my Width, myHeight 

OSType 

myType: 


OSErr 

myErr noEcr; 


ClearMoviesStickyErrorO r 


// gtt die first vi(ko track in the source movie 

mySrcTrack - GetMovlelndTrackTypa(theSrcMoyie. 1. 

VldeoMediaType. itiovieTrackMediaType) ; 
if (mySrcTrack = NULL) 
returnCparamErr); 

// the track's media ;ind dimcnsiiins 
mySrcMedia * GetTrackMedla(mySrcTrack)* 

GetTrackDinenfilona (mySrcTrack. ^rnyWldth. iniyHeight); 

// create a destination track 

myDstTrack “ NewMavieTtack(theOstMovie, myWidth. tnyHeight* 
GetTrackVolumeCmySrcTrack)): 

// create a destination media 

GctMediaHandlerDGacriptlcin(mySrcMedia* SmyType. 0» 0): 
myOatHedia = NewTrackMedia[myDstTrack, myType. 
GetMediaTinieScslstniySrcMedlaK 0, 0); 

// copy the entire track 

InsertTrackSegnient(mySrcTrack, tnyDstTrack, 0, 
GetTrackDuration(tnySrcTrack), 0): 

GopyTrackSettinga {tnyS rcTrack. myDstTrack): 

SetTrackLayer [myDstTrack, GetTrackLayer (niyStcTrack)); 

// an object video track should always be enabled 
SetTrackEnabled[myDstTrack, true]: 

if (thelnmgeTrack !- NULL) 

'thelmageTrack = myDstTrack: 

return(GetMoviesStickyError0); 

1 

As you can see, we call ClearMoviesStickyError at the beginning 
of this function and then return to our caller the value returned 
by GetMoviesStickyError. Tlie idea here is that our caller will 
care only about die first error we encounter wliile executing this 
funaion, w^hich will of course he the sticky error (since we 
cleared the sticky error at the beginning). 

Another case where we may want to access the sticky 
error is when we know' or suspect that a QuickTime function 
will report an error, but we don't really care about that error. 
Listing 4 defines a function, QTUtil,s_GetFranieCount, which 
returns die number of frames in a specified track. We use 
GetTrackNextlnterestingTime to step through the track's 

list ing 4i C onntiii g the frames in a track _ 

QTlJtilii_GctFrameCoiint 

long QTtjtils_GetFraTiJeCount [Track theTrack) 
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long myCount ^ -1; 

short myFlags: 

TlmeValue myTitne = 0: 

OSZrr myErr = noErr; 

if (theTrack = MLL3 
goto bail: 

inyErr ^ GetMoviesStickyErrorO ; 

// we want to l>egm with the first Prauic (sample) in the crack 
inyFlags = rkextTimeMediaSajnple + nextTiifleEdgeOK: 

while (iiiyTlme >= 0) I 
inyCoiitit++: 

// look fijr the nest fmine in file track; when there arc no more frames, 

// myTime is set to -I,so we'M exit the while loop 
GetT rac kHext I nt a r e s t i n gT ime (thaT rack, my F lags, my Time + 
fixedl, fiimyTime. NULL): 

// after the first interesting time, donl include file time we're cunently at 
myFlags = nextTimeStep: 

1 

if (myErr = noErr) 

GlearMoviesStickyErrorO : 

ball: 

return(myCount): 


GetTrackNextInterestingllme returns, in the sixth 
parameter, tlie first time value it finds that satisfies the search 
criteria specified in the Hags parameter. When it cannot find a 
time value that satisfies those criteria, it sets tliat parameter to -1, 
For all we know, it’s possible that CietTrackNextlnterestingTime 
also sets an error value; if so, w'e want to clear that value by 
calling ClearMoviesStickyError (but only if the sticky error on 
entry to our function was noErr). 

Erkor Notification FinvcriONS 

QuickTime provides the SetMoviesErrorProc function, 
which we can use to install an em^r notification function (or, 
more briefly, error function). An error notification function is 
called whenever QuickTime encounters a non-zero result code 
during the execution of a Movie Toolbox function. 
SetMoviesErrorProc is declared like this: 

void SetMoviesErrorProc (MoviesErrorfiPP errProc. 
long refcon): 

The first parameter is a universal procedure pointer to our 
custom error notification function; the second parameter Ls a 4- 
byte reference constant that is passed tc3 our error function when 
it is called. The error notification function is declared like this: 
void MyMoviesErrorProc (OSErr theErr, long theRefcon); 

Tlie first parameter is the non-zero result code that w^as just 
encountered, and the second parameter is the reference constant 
we specified when we called SetMoviesErrorProc. 

An error notification function is useful during application 
development or debugging, as they provide a single location 
where all errors are reported. Tliis keeps us from having to put 
breakpoints all through our code as we track dowm problems. 


Mysterious Errors 

While we're on the topic of retrieving errors in QuickTime- 
savvy appliaitions, ifs worth discussing an issue that trips 
people up occasionally, 'fhis is the issue of mysterious 
QuickTime errors Hke -32766, which can occur when we 
execute some code like this: 

OSErr myErr = GrapMcsExportSetDeptb{myComponent, 32): 

When tills code is executed, dien for certain graphics exporters, 
myErr is set to -32766. If we look in the file MacErrors.h, we 
won't find any such error. WhaEs going on? 

The explanation is surprisingiy straightforward: 
GraphlcsExportSetDepdi and many other QuickTime functions 
that work with componenLs return a function result of type 
ComponentResult, which is declared like this: 

typedef long ComponentResult: 

On the other hand, the OSErr data type is declared like this: 

typedef Slntlfi OSErr: 

When we try to dr a ComponentResult into an OSErr, we get 
only the low-order l6 bits, interpreted as a signed value. When 
the ComponentResult is noErr, this truncation is unproblematic. 
But several component errors use the full 32 bits {if the long 
word, in which case the truncation will give us the mysterious 
errors described above. In particular, if a component does not 
supp{>n a particular action, then it will return the value 
badComponentSelector, which is defined as 0x80008002. 
Truncating 0x80008002 to a 16-bit signed quantity gives us 
-32766. That's what’s happening with the call to 
GraphicsExportSetDepth we just considered: the particular 
component specified by the myComponent parameter does not 
support setting the export bit depth, in which case it returns 
badComponentSelector. 

The lesson here is simple: pay attention to die data type of 
a function’s return value and make sure you have enough space 
to hold that value. More specifically: don’t use a variable of type 
OSErr to hold the return value of a component-related function 
whose return value Ls of type ComponentResult. But don’t feel 
bad if you slip up occasionally. Ttiis mix-up is in lace so common 
that the die MacErrors.h contains some helpful commenLS: 

r ComponentError cxxtesV 
enum 1 

bafiComponentlnstance’^ (long)0x80008001, /* when cast to an 
OSErr this is -32767*/ 

badComponentSelector- (long)0x80008002 /* when cast to an 

OSErr this is -32766*/ 

] : 

A Framework Bug 

Let’s close this article by squashing a particularly nasty bug 
that I introduced into our sample applications a few months 
back, when we updated our Macintosh code to use Carbon 
events instead of ‘"classic” events. (See “Event Horizon" in 
Maclecb, May 2002.) Recall that we added a Carbon event loop 
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timer to each open movie window, so that we can periodically 
task the movie controller (by calling MClsPlayerEvent or 
MCIdlc). Unfortunately, our existing application can crash — at 
least on Mac OS 9 — if we do something so simple as open a 
movie window and then later close it. That's not good. 


Fixing the Bug 

The problematic code turns out to be in the Macintosh 
version f>f the QTFTame_CreateMovieWindow function, shown 
in Listing 5. Here we create a new window and window object. 
Then we attach standard and custom Carbon event handlers to 
the window. Finally, we call InstallEventLcx^pTimer to attach a 
timer to the window. 


Listing 5: Creati|ig_a movie window _ 

QTFrame_CrcattMovieWin[low 

WlndowReference QTFratne_C5:eateHovieWiiidotf (void) 

I 

Windoii^Reference inyWindow ^ HULL; 

// create a new window to display the movie in 

inyWindow = NewCWlndow(KULL, fiigWindowRect, gWindowTitle. 
false, noGrovDocPiroc, (WindowPtr) - IL, true, 0); 

// create a new window object associated with the new window 
QTFrame_GrsateWindowObject fmyWlndow): 

#if USE_CMBOH_EVBHTS 

{ 

EventTypeSpec inyEventSpec [] " I 

(kEvetitClassKeyboard. kEventRawKeyDown ) * 
(kEventClassKeyboard. kEventRawKeyRepeatI. 

{kEventClassKeyboard, kEventRawKeyUp1. 
fkEventClassWindow, kEventyindowUpdatej, 

I kEventClassWindow, kEventWindowDrawContentI * 
fkEventClassWindow. kEventWindowActivatedI, 
f kEventClassWindow, kEventWindowDeactivated|, 
IkEventClasaWitidow. kEventyindowHandleContentClickl. 

(kEventClassWindow * kEventWindowClose J 
h 


// install Carbon event handlers for this window 
InstallStandardEventHendler 

(GetWindowEventTarget(myWlndow)): 

If [gWinEventHandlerOPP != NULL) 

InstaliEventHandler CGetWindowEventTarget(mytfindow), 

gWinEventHandlerUPF, GetEventTypeCount(myEventSpec), 
myEventSpec, 

(3TFrajne_GetWindow<]bjectFromWindow (my Window) ♦ HULL) : 

1 

if (gWinTimerHandlerUPP 1= NULL) 

rnstallEventLoopTimer(GetHainEventLoop{)♦ 0. 

TicksToEventTiuie (kWNEMininniroSleep), 
gWinTimerHandlertJPP, myWindowOb j ect, 

& (• *i!iyWiiidowObjfict) , fTiffierRef) ; 

#endlf 

return(myWindow): 

I 


It turns out that InstallEventLoopTimer can move memory, 
which might invalidate its last parameter, 
&(**myWindowObject).fTimerRef. If the window object indeed 
moves, then InstallEventLoopTimer will write the timer reference 
into the previous location of the window object* Thai’s bad 
enough, but it gets worse when you realke that the window 
object, in its new memory location, now won’t contain the timer 
reference returned by InstallEventLoopTimer. Rather, 
(**myWindot\ObjeaTfrimerRef wQl still NULL, 'fhe event loop 
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timer indeed gets installed, l:jui we don't have a reference to it. 

I’his in itself isn’t a problem until we try to remove the event 
loop timer when the window is dosed. Here’s the code we use 
to do that: 

if (('*myWindowObject) *fTiiiierRef NULL) 

RemoveEventLoopTiraer ((* *TnyWindowObject) .fTimerRef) ; 

Since {••myWindQwObjectl.fTimerRef is indeed NULL, 
RemcweEventLfxipTiiner isn't called and the timer continues 
firing even after the movie window has disappeared. Listing 6 
shows our even! loop timer callback function. 


Listitig^&JiancUiiig ev ent loop timer callbacks_ 

QTFranic_( ^rbcmE^'entWindc.i wTiintT 
PASGAL_RTH void QTFrame_CarboTiEventWlmiowTipier 

(EventLoopTimerRef theTimer. vt>id “theRefCon) 
i 

f/pragm unua ad (theTimer) 

WindowObject myWindowObject ^ (WindowObject)theRefCon; 

// just pretend at null event hats been received.,., 
if ((niyWindowObject 1= NULL) U 

[ C**Ei]yWindowObject3 ,fController != NULL)) 
if {1gMenuIsTracking [[ gRunningUnderX) 

MCIdle((**iiiyyindowOb]act) .fController) : 

I 


If the window object has been disposed of, then reading any of 
its fields (in this case^ fCtmtroller) will likely result in a 
segmentation fault or other error. 

This is a classic case of using a dangling pointer^ the 
address of a blrxk of memory whose contents have moved. 
You can get the full details on this type of problem in the book 
Inside Macintosh: w hich 1 am presently chagrined to 

admit 1 myself wrote a decade ago). There are several 
solutions to this type of problem. A standard solution is to 
lock the window^ object before calling InstallEventLoopTimer 
and then unlock it afterw^ards: 

HLockt (Handle) myWindowObject); 
if (gWinTimerHandlarUPP r= NULL) 

IngtallEventLoopTimer(GetMainEventLoopO, 0* 

TlcksToEventTirae [kWNEMinitnumSleep). 
gW i nTime tHaud 1 e r U P P. irryW ind a wOb j e ct. 

£i {• *myWindowObJ ect) * fTirnerRef) : 

HUnlockt (HaTidlejTiiyWiELdowOb ject) ; 

Or, even more simply, we can just use a temporary' variable to 
hold tlie timer reference: 

EventLoopTimerRef myTimerRef: 

if (gWinTimerHandlerUPP 1= NULL) 

TnstallEventLoopTimer[GetMainEveatLoop[), 0, 

TicksToEventTime(kWNEMinimuraS1eep)* 
gWinTlmerHandlerUFF. myWiiidowObject, 

SiayTimerRef) : 

('*rayWindowGbject).fTirnerRef = myTimerRef: 


Adding Some More Protections 

Let's take tliis opportunity to tinker with the Carbon event 
lot^p timer callback function QTFrame_(^rlx^nEventWindowTimer 
(Listing 6, alxDve). Fii^t of all, we should add a check at the top 


of the function to make sure we got a non-NULL window object: 

if (myWindovObject = NULL) 
return; 

And we should make sure that we are passed the same timer 
reference we are storing in the window object: 

If {(**myWliidowOhject) .fTirnerRef [= theTimer) 
return: 

More importantly, 1 want to change the call to MCIdle into 
a call to MCIsPlayerEvent, We can achieve this end by building 
a null event and passing it to our framework function 
QTFrame_HandleEvent, as shown in Listing 7, 

Listing 7 *- Handling event loop timer callbacks (revised) 

QTFranie_CarbofiEventWijadow'Timer 
PASCAL_RTN void QTFrame_CarbonEventWindowTimer 

(EventLoopTlujerRef theTimer, void HheRefCon) 

( 

WindowObject tnyWindowObject ^ (WindowObject)theRafCon: 

if (myWindowObject = NULL) 
return: 

// sanity check; make sure it’s our timer 
If (Wind0wObject), fTimerRef 1= theTimer) 
return; 

// just issue a null event to our evenrhandling routine.... 

If {IgMenuIsTracking || gRunnlngUnderX) i 
EveutSecordmyEvent; 

myEvent.what = nullEvent; 
myEvent.message = 0: 
myEvent.modifiers = 0; 

myEvent.uhen = EventTimeToTicks(GetCurrentEventTime()): 
QTFrame_HandleEvent(&myEvent)r 

1 

I 

1 prefer this revised approach to tasking our movie 
controllers because it routes null evenLs through our existing 
event-handling routine QTFrame_HandleEvent. This in turn will 
make it easier to modify our cc}de to handle movies that need to 
lie tasked but which don't yet have a movie controller attached 
to them. In the next article, we ll see how this can happen. 

Conclusion 

Of the four new QuickTime functions we’ve encountered 
in this article (GetMoviesError, GetMoviesStickyError, 
ClearMoviesStickyError, and SeiMoviesErrorProc), weTe most 
likely lo want to use GetMoviesError in our daily programming, 
as it provides our only means of retrieving the result codes for 
a large number of QuickTime functions. I generally find the 
sticky error less useful, but there are times we might w^ani to 
take a look at it. The error procedure is, to my knowledge, 
largely unused. I can, however, imagine that a clever 
programmer could find some useful applications for it, so it's 
good to at least know^ it exisLs. 
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MAC OS X 


By Andrew C. Stone 


The Philosophy of Cocoa: Small is Beautiful 
and Lazy is Good 


] believe programming renaissance is upon us—and 
Cocoa, Apple’s high level object-oriented framework is at the 
heart of iL By wrapping complexity inside easy-to-use 
objects, Cocoa frees application developers from the burden 
of the minutiae that so often drives developers crazy- Instead, 
they can focus on whaCs special about their applications, and 
in a few lines of code, create a complete OS X application 
that seamlessly interoperates with all other OS X 
applications. And, for very little additional effort, they get 
AppleScriptability as well. 

IVe been living and breathing Cocoa and its various 
previous incarnations for 14 years now, and have noticed 
that my applications are getting more features with smaller 
amounts of code each year. This article will explore some of 
the truisms and gems hard earned by hanging in the trenches 
lo these many years. 

Smau. is Beautiful 

ICs no coincidence that we use the term “architecture*' 
for the overarching structure of an application. I received my 
baccalaureate in classical Architecture in the 70’s when the 
visionaries of the time were rebelling against the huge 
concrete boxes that crushed the human scale and spirit. E. E 
Schumacher, in Small is Beautiful — A Study of Economics 
as if People Mattered: 

"What I wish to emphasise is the duality of the human 
requirement when it comes to the question of size: there is 
no single answer. Eor his different purposes man needs 
many different structures, both small ones and large ones, 
some exclusive and some comprehensive. Yet people find it 
most difficult to keep two seemingly opposite necessities of 
truth in their minds at the same time. They always tend to 
clamour for a final solution, as if in actual life there could 


ever he a final solution other than death. For constructive 
work, the principal task is always the restoration of some 
kind of balance. Today we suffer from an almost universal 
idolatry of giantism. It is therefore necessar)f to insist on the 
virtues of smallness - where this applies. (p. 54) 

1 believe this thinking still rings true 30 years later in 
cyber'architeciure. 

From the programming classic The Mythical Man Month 
by Frederick P. Brooks, Jr., we learned that the more 
programmers you throw at a project, the less likely the 
project will ever be finished! From this follows that a project 
.should have one central architect, with rather fascist control 
over Feature set and implementation, especially if you want it 
to ship in a timely fashion. Cocoa gives you tlie tools needed 
to build full-featured, world-class applications with just a 
handful of programmers. For best effect, these programmers 
should be lazy... 

Lazy is Good 

Laziness is a virtue, believe it or not! I often describe my 
style of a computer .scientist as someone who is .so lazy that 
they'll spend days writing software to save a minute each 
time the task is performed from then on. There are two forms 
of laziness that Cocoa embraces: lazy loading of Qbject.s and 
just plain lazy programming. 

Bundle it Up 

Lazy loading lets full-featured applications like Stone 
Design's Create®, a three-in-one illustration, page layout and 
web authoring app, launch in just a few seconds. Compare 
that to a legacy Carbon application with half the features 
which takes rainotes to launch! By using dynamically loaded 
bundles, you do not use memory or resources until the end 
user actually needs that particular feature and its related 


Andrew Stone, CEO of Stone Design, www.stone.com, has been the principal arclntect of several solar houses and over a dozen Cocoa applications 
shipping for Mac OS X. 
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resources, Moreover, you can update and distribute jusi the 
tiny bundle instead of the whole application should, heaven 
forbid, a bug be found! 

To use dynamically loaded bundles, you need to be able 
to compile your application without actually referencing the 
loadable object directly. We do this runtime magic by only 
referring to the dynamically loaded class, the principal class 
of the bundle, by its name as a string. 

Typically, the type.s of objects that do well being loaded 
dynamically are the numerous special editors and interfaces 
in a program, .such as an arrow or pattern editor and the 
classes it needs to provide the interface. The following 
conditions make up a good candidate for a loadable Imndle: 

* Has resources that are not alw^ays used each session 

• Doesn't contain core data model classes (these should be 
linked) 

A typical example might have an NSWindowController 
subclass and perhaps some custom views and images in the 
bunclle. We load this type of bundle by having it respond to 
the class method “+sharedlnstance", since you usually only 
need one of these t>hjeccs per application; 

- (void)loadAUniquelnterfaceObjectAction:(id]sender { 

// we only us« the luinie of the bundle, not its class 

// which would cause an undefined symbol when tLnking: 

[ [ [NSApp delegate] 

sharedInstanceOf ClasaNntne : ^''HytfnlqueControllet1 
showWindovtself]: 

1 

But, with the introduction of sheets, two or more 
documents may want to load the same bundle (for example, 
a custom zoom sheet) at the same time. In this case, you'll 
want a unique instance, which will be released after use. 
These principal clas.ses of bundles need only re.spond to - 
(id)init, which all objects do anyw^ay .since they inherit from 
NSObject which implements -(id)inil; 

- (void)ioadAPerDocumentInterfaceObJectAction;(id)sender [ 
[[[NSApp delegate] 

instanceOfClassNatne :^^'MyPerBocumentController"'] 
showWindow;self] ; 

1 

And, because we are lazy and more importantly, good 
programmers, we filter both of these methods through one 
factored method, -(id)instanceOfClassName:tNSStnng *)name 
shared;(BOOL)shared like this: 

- (id) sharedlnstatLceOfClassName: (NSStriug *) name 
I 

return [self instanceOfClassName:name sharediYES]: 

I 


- (idiinstanceOfClassName:(NSString *)name ( 

return [self instanceOfClassName:name shared;NOl; 

[ 

And here's the non-linked bundle loading code for both 
of them, which we place for convenience in tliG globally 
available [NSApp delegatel class: 

- (id)instanceOfClassWame:(NSString *)name 
shared:(bOOL)shared 

( 

id obj = nil: 

NSStting *path = [ [NSBundle mainEundle] 
pathForResource :naitie ofType :^''bundle"] ; 
if (path] [ 

// wt found tilt bundk, now load it: 

NSbundle *b = [ [NEBundle allocWithZone:NULL] 
lnitWithPath:patb]: 

// if it loads, sec if it lias a valid principalCiass - this k set in PB's target 
inspector 

if ((b 1= nil) ( [b principalGlass] l^NULL)) [ 

// hero i'i the only difference between a single shared instance 
// and a new one every time; 

if (shared] obj “ [ [b prlncipalClass] 
sharedinstance] : 

else obj = [ 1 [b principalGlass] 
allocWithZons:NULL] init]; 

1 else i 

//'nils is for debugging in case it can’t be loaded: 

N£LDg{@”Can't Load path]; 

I 

] else NSLog(@'"Couldn ' t find bundle !\n’'.name) : 
return obj; 


Felt Tip Software presents 

Sound Studio 2.0 


Built for Mac OS X 

With Sound Studio 2.0, you can: 

Digrtiz# cassette tapes and vinyl records to make CDs 
Record live performances and interviews 
Record your favorite radio programs with Timer Recording 
Edit out dead air, glitches, and mistakes in recording 
Apply any of 19 effects including Reverb and Chorus 
Create new sounds and loops 

Sound Studio is an audio recording and editiiig application built for 
Mac OS X. It can also run on Mac OS versions 8.1 and up. Some 
systems may need a USB audio input device to record. 

Only $49.99 
Download 14-day trial version at 

http;//www.felttip.coin/ss/ 

felt tip software 

807 Keely Place. Philadelphia. PA 19128, USA 
www.feitttp.com 
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ConceptDrouj" 

PROFESSIONAL 


Cross-platform diagramming and drawing tool 



With CoftCcplDrauj™, you can 
create diagrams, schemes, pians 
and maps easily. Use 2700 pre¬ 
drawn objects to quickly create 
documents, and export them to 
HTML or PowerPoint to present to 
your colleagues or clients. Works 
under Mac OS X, Classic Mac OS 
and Windows. 


Use CoftccptDrouu Pro for: 

• UML 

• Network Diagrams 

• Flowcharts 

• Web Site Schemes 

• Interface Modelling 

• Process Flow 



rX 

Mac Windows ^ 



Download demo or order online at: 
www.conceptdraw.com/professional 
e-mail: sales@conceptdraw.com 


Code Lazily 

Lazy programmmg means “Use the *Kit, Luke!” Every 
standard data structure and a complete set of API’s are 
already available to you, so there is rarely a need to reinvent 
your own. Therefore, this lazy programming axiom has a 
corollary: 

If it’s hard to do or understand, it’s wrong 

By this I mean any coding solution that involves 
convoluted logic or going beneath the API (using 
undocumemed methods) is probably not the right approach. 
Taking the time to understand what’s already offered to you 
is well worth the effort, because Cocoa, and its underlying 
frameworks, Foundation and AppKit, have evolved over l6 
years to provide the basic building blocks of an object 
oriented solution. Many times when Fm adding a new 
feature, Til try one brute force approach, notice how 
cumbersome it is, re-read the AppKit or Foundation API and 
find a much a better solution involving much less code. 

For example, 1 recently added a “Clone Client” feature to 
TimeEqualsMoney™ - take the current docuraent’s data, 
remove the individual time entries, create a new document 
with all the same settings except no time entries. It was six 
lines of code and it worked the first time: 

- (void] cloneDocujnentActioni (id) eender 1 
// make a new untitled - have it read owr document: 

NSMutableDictlonary ^doc = [self 
workDocumentDictionaryl: 

MyDocument ‘newDoc “ I [NSDocumentController 
aharedDocuinent Controller] 

openUntltledDocumentOfTypetDocumentType display:NO]: 

[doc temoveObjectForKey:WorkKey): 

[nRwDoc loadDataRepresentation:[[doc description] 
dataUsingEncodln&mSASCIIStringETicoding] 
ofTypetDocumentType]; 

[newDoc makeWindowControllers]: 

[[[newDoc windowControllers] objectAtlndajc:O] 
sbowWindov^: self I ; 

I 


Instead of hiring programmers, why not let the entire 
Cocoa team at Apple be your engineers? When you use the 
Kit and Apple puts in new^ functionality and bug fixes, your 
application automatically gains these features and fixes. Your 
efforts should he focused on creating a mapping between the 
real world problems you are solving and the objects that 
represent them. Which brings me to my next point: 

Put The Code Where It Belongs 

One of the biggest challenges facing newcomers to 
Object Oriented Programming is placing code in the right 
object. Because many of us grew' up with “procedural” 
languages like Basic, Pa.scal, and C, and because old habits 
die hard, we need to let go of trying to tell things what do 
to do, and instead, let them figure it out for themselves. Let’s 
say we have a document w^hich is a list of pages, which 
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contains a list of graphics, which are simple graphics or //den page we need to be redrawn 

groups, which contain a list of graphics, which are graphics t^elf tellHyPageToinvaiidateMyBounds]: 

or groups which contain, etc... And let's say we want to set | 

the ''isVisible’' state of all the graphics in the document. 


The procedural approach would be to assume absolute 
knowledge over this hierarchy, and you’d blithely code 
something like this; 


@impleinentation MyDocujnent 
// please don't do this! 

- {void}BetA110bjectsVlsible:(BOOL)isVinlble [ 
unsigned int i, pageCount = [_pages count]: 
for (i “ 0: ± < pageCount: i++) [ 

Page ‘p = [_pages obiectAtlndex:i] : 

NSArray 'graphics = [p graphics]; 

unsigned int j , graphicsCount = [graphics count ]: 

for (j = 0: j < graphlcaCount: j++} ( 

Graphic *g = (graphics objectAtltidex: jj : 
if ([g isKindOfClass:[Group class)) [ 

NSArray 'groupGraphics = [g graphics]; 
unsigned k.gtoupGraphlcsCount = 
[groupGraphics count]; 

for (k “ 0; k < groupGcaphicsCount: k++) 

I 

// since this only rccurses one level, this code is wrong as 
// well as very liarti to read and maintain!!! 

Graphic ‘groupedGraphic = [groupGraphics 
objectAtIndextk]i 

[k setVislble:isVisible] ; 

I 

else [g setVisible;isVlsibla] : 

I 


) 

// tlie 00 way : 

^implementation MyDocument 

' (vciid)setAllObjectsVlsible; (BOOL)isVislble [ 

[_pages 

makeOb jectsFerformSelectCir : ©selector (setAl 10bj ectsVisible :) 
withObject:(id)isVisible]: 

) 


Simpleinentatlou Page 

- (void)setAllObjectsVlsible; (BOODlsVisible I 

[_graphics 

makeOhjectsPerformselector:©selector(setVisible;) 
witbObject:(id)lsVlslble]: 

1 


// groups need to recurse dowa the hierarchy until individuaJ graphics 
// are found.., 

©implementation Group 

- (void)setVisible:(BOOL)isVialble i 
Lgraphics 

makeOhjectsPerformSelector:©selector{setVisible;) 
witbObject:(Id)isVisible]r 


©itnplementatloti Graphic 
- (void) setVisible: [BOODisVlsible ( 

// only do work If you absolutely have to - remember lAZY! 

if (^isVisible != isVieible) [ 

// you'd probably do undo manager stuff here 
_isVislble " isVisible; 


Conclusion 

The more you understand object oriented programming 
and Cocoa, the smaller and more reusable your applications 
will become. And they will load with lightning speed! But 
more importantly, you’ll have less code to maintain which 
means less bugs, less headaches and more time to enjoy life. 
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REVIEWS 


By Michael R, Harvey 


DAVE 

Dave, from lliursby Sofov'are, is the gold standand when it 
cornea to cross pktfonn file and printer sliaring. It is die best seller 
utility of it’s kind, and shows every sign of remaining so. Features 
added to tlie latest version include support for Unicode file names, 
tlie ability to access files larger than 2 GB, and the availability of the 
program dcxaimentation via the Help Center, among others. 

installation of Dave is a breeze. In OS 8 and 9, run the installer, 
tlien restart. In OS X, ncK even a restart is needed. Dave is ready to 
go immediately. 



Cormectirig to Windows shares using 
Daw in OS A" ami OS 8 and 9. 

Configuration of Dave is simplidW itself. After installation, 
simply follow the in.structjons in the Setup Assistant. The assistant 
will query you for the infonnation it needs to establish a cotinection 
to the Windows servers on your network, like ^INS server address 
and Workgroup name. You will also have the option during setup 
to share out a folder from your Mac to the Windows machines on 
your network. This can be done now, or skipped over. Tliis setting, 
as well as all the others, can be changed at any time by gomg back 
tlirough tlie Setup Assistant again. Running the Assistant starts you 
over at the 1 beginning, but ail your previous infonnation will be 
there. You can easily make changes only to die aretis you need, 
skifiping past tlie parts that do not require updating. 

Accessing Windows serv'eis via Dave is now just like accessing 
any other network volume. The specifics of how depend on w hich 
ojx^rating system you are running. 

In Xf accessing ’Windows serv'ers is done via die Connect 
to Server window. The beliavior Ls identical to mounting a .sever via 
AppleTalk. From die Go menu, select Connect to Serv^er. r>ave 
Netw'ork appeiirs along with AppleTalk and Local Network. Click 
on it, and you will get a listing of domains and workgroups. Choose 
die one you want to access, and a Hsdng of available shares for that 
domain wall pop up. From there, just double click on the share you 
w^ish to acce.ss, and logon as usual 

In Mac OS 8 and 9 t you access those heretofore unreachable 
Windows shares via the Chooser. Once open, a Chooser 
extension named Dave Client is listed along with the usual 


selections, like AppleSliare. Clicking on it waD lei you browse the 
eniire network, mount a share manually, or select from the 
available list of Windows boxes on your network. Double click 
on the share you wish to access, enter your logon and password, 
as you would normally, and you are in. 

Thursby provides some nice documentatic^n to gel you up and 
running. A printed Quick Start Guide will have you conneaed to 
your Windows network in minutes. For bath OS X, and 8 and 9, 
extensive material is accessible via the Help Center, found in the 
Help menu. The Help Center data is well laid out, and finding 
answers is fairly easy. Some of the material to be had includes 
detailed set up instructions, and answers to common questions, A 
troubleshooting guide is key among the available material, 
providing e:5Uensive information on possible errors tliat you may 
encounter, and likely solutions. 

There have been some problems witli die version 31 release 
of Dave. Thursby has l3een working to resolve these issues. In early 
May, they released version 31.1 to address some of these issues, as 
well as add features. Check the Read Me file for ak the gory details, 
'fhursby also maintains an up to dale FAQ on it’s website, that you 
can link to from tlie Help Center, that answc^rs many of tlie 
questions you may liave regarding installation, networking, or any 
otlier problems. 

Anotlier great resource for finding solutions to problems 
with Dave is the website, MacWindows. It deals with all issues 
relating to Mac and Windows integration, and is a great resource 
for troubleshooting not only Dave, but all aspects of cross 
platform networking. 


_ CaniKct t o Sifver__ 

Cfvooti 1 i«nnr from the lift, or entcf a urvcr ftddresf 
Al. "fewoiiCGRQUP _ID0 

_ ^WOSKGRDUP f 

gi DAvr Nenvprh ^ 

LeuI HctwoHt ^ 


0 flemi Se4JUiin^.. O 

Address _ 

^ AddTgFavortiTt ^ f Cancel 3 Comwer ^ 

_ A 

Thuishy Software sells a range of products for connecting Macs 
and Windows PC’s together in environments ranging from the home 
office to the corporate LAN, Tlie>" even offer a product, MacNFS, 
available to make connecting to Unix .servers a simple process. If 
you plan on a^as-s piatfoim netw^orking in OS X, you’ll need Dave, 
Dave has an MSRP of Si49 for a single license. Thursby also offers 
an Annual Update program. Tills program will give you all updates 
that are released within the m^elve montlis of the contract. Pricing 
for the Annual Update program starts at $49.95 for a single license, 
up to $900 for fifty licenses. 

http://i?^Tvw.diursby.com/ 
http:// WWW. macwindow s.conV 
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WEBOBJECTS 

DEVELOPMENT 


By Tom Woteki 


Reusable WebObjects Components 


Introduction 

One of the more interesting and powerful features of 
WebObjects is the ability to construct reusable components. 
However neither the documentation nor any of the available 
books on WebObjects cover this topic v^vy well. The best 
discussions are in Professional WehOhjects 5.0 wiih Java 
(DeMan, et. ah 2001), and the Windows and version 4.S- 
orienied WehOhJecLs Web Applicaiion Construction Kit (Ru^ek 
2001). Botli of these ireatments, though instructive, leave a lot 
to tile reader The common example that both books cover is 
how to construct a standard template for an application. 

This article illustrates how to build reusable components 
using ViK’o examples drawm from a WebObjects application I 
wrote to maintain records of a wine collection. It also 
illustrates creating custom component bindings and 
communications between components using key-value 
coding. I'he example components have wide applicability to 
the maintenance of reference tables and are easily generalized 
to maintaining any single attribute of a database table. 

This article assumes you are familiar with at least the 
basic.s of building a WebObjects database application 
including using interface w^idgets, forms, actions, data models 
and display groups. 


High-Level Design 

Tlie approach I took was to develop two comfxments, each 
designed to lx? emlxdded in a form witJiin a parent component. 
One component, tiie '"selector'', is used eitlier to select an existing 
record to edit or to initiate insertion of a new^ record. The otlier, the 
""ecUtur'; is used to actually edit die selected record or cTefite the new 
one. The wo componenls communicate widi each other thmugh 
key-value coding whereby the selector passes the user's intent and 
otlier information to the editor. We use bindings to designate the 
specific table and attribute the componenls should edit. 

Figures I and 2 show the respective finished products, each 
embedded in parent components. The selector component in 
Figure 1 consists only of the WOPopUpButton and the two form 
buttons '“Kdit" and “New'\ The former button initiates an update 
tjf a selected record, the latter initiates insertion ol’ a new' record. 
The remaining aspects of the interface, such as the prompt 
string, pertain to parent components such as the page itself 
Similarly, the editor component in Figure Z consists only of a 
WOTextField and two form buttons. The separate implementation 
of the components, apart from communications via key-value 
coding, and their separation from aspects of the surrounding 
interface, including the form they are emlmlded in, maximizes 
their reusability and adaptability to different interface designs. 


The Example Problem: Maintaining a Reference Table 

A common type of table in a databa.se application is a 
reference table, that is, a table consisting of two colLimns: a 
primary key and the attribute of interest. An example is a 
table of country names. In my application there are reference 
tables for wine producing countries, wane regions, wine 
names and so on. Given such reference tables, an obvious 
need is to maintain the tables, either to add new records or 
to update existing records. Because my application uses 
multiple reference tables, and noting the obvious generality 
of the situation, I decided to develop some reu.sable 
components for maintaining any reference table. We’ll see 
how to use these components in an example appHcalion to 
maintain a reference table of country names. 
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This demonstration application jfluscrates the 
use of reusable WebObjects components and 
inter-component communication. 


Country:! 




LomI htriftriLa 


^ Select Count 


Afghanistan 

India 

Pakistan 

USA 



Figure I: We finished selector component in action 


In addition to being a Macintosh and WebObjects hobbyist developer, Tom Woteki, aka Dr. Wo, is a vice preuSident at TRW Systems. He can be reached 
at dm'o@WGteki.com 
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Electronic Software Distribution - safely protected by WIBU-KEY. 

Web Remote Programming 

Reprogram the WIBU-BOX hardware at the customer's site directly 
via the Internet. 

Web Authentication 

Secure authentication via a two-way-encryption 

Pay-Per-Use 
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MacOS9&X 
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Figure 2: The finished editor component in action 


Detailed Design 

Now let’s consider details of the preceding design. First of 
all, let’s name the components we’re going to build 
WOObjectSelector and WOObjectEditor. Viewing Figure 1 it 
should he clear that we must at least provide WOObjectSelector 
the list it should display in its WOPopUpButton menu and the 
page(s) to return when either its ‘Edit’" or "‘New’’ buttons are 
clicked. In this design Ixnh butums will return the same page. 
We might also want to provide the component a “no selection" 
string to display when there is no selection in the pop-up. Since 
we are editing a reference table, you can anticipate that we will 
bind a WODisplayGroup to the pop-up's display list. And you 
might anticipate that the return page for the buttons should be 
some page that encloses WOObjectEditor as a child component. 
Before we discuss tliese details, including how to provide 
WOObjectSelector the information it needs, let's consider what 
WOObjectEditor needs to do its job. 

Viewing Figure 2, we can see that we need to provide the 
editor at least the data fcjr tlie attribute of the record we are 
editing (in our example, the name of a cf3unlry) plus the return 
page for tlie form bult(3ns. Even mtrre is needed, however. First 
of all it would be helpful to know if we are updating an existing 
record or inserting a new one. Second, if updating we ll need the 
record itself, not just the data for the attribute of interest. In 
order to achieve reu.5ability, we'll provide not only the record, 
but the key for tlie attribute as well, so that we can use the 
powerful generality of key-value coding to update the value of 
any attribute. Finally, in case of inserting a new^ record, well 
need to create the record and insert it into the default editing 
context, so we'll need to provide WOObjectEditor the name of the 
entity to create as w^ell as the key for the pertinent attribute. 

Which component will provide WOObjectEditor the 
information it needs and how? WOObjectSelector knows 
whether the user is updating or insening by means of the 
button the user clicks. If updating, it also knows the record the 
user is updating, namely the one corresponding to the item 
selected in the display lisL So, WOObjectSelector is the logical 
provider of this information, [t will do st> by invoking the key- 


value coding method takeValueForKey (w'hich is inherited by 
any class that extends WOComponent) on the parent page dial 
encloses WOObjectEditor. !i wall invoke the method for each of 
a series of keys corresponding to the data needed by 
WOObjectEditor. The parent page for WOObjectEditor is also the 
return page for WO Objects elector's buttons. This page, having 
received the required values from WOObjectSelector, will set 
the values needed by WOObjectEditor using API bindings. (Note 
that assignments specified by API bindings are performed 
behind the scenes by WebObjects using key-value coding.) 
Finally, the additional information needed by WOObjectEditor, 
such as the name of the entity we are working with, will be 
passed through from the parent page of WOObjectSelector using 
the same techniques. 

Figure 3 neatly summarizes the flow of infonnation and the 
method.s for communicating lx?tween components. The parent 
page of WOObjectSelector passes to it the global context, namely 
entityName and attributeKey, plus the information llie selector 
specifically needs using API bindings. WOObjectSelector then 
passes the global context along with other specifics that 
WOObjectEditor needs, such as the user’s .selection, to the latter’s 
parent using key-value coding. Finally, the editor component’s 
parent passes the information to it using API bindings. 
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figure J. 


Now let's consider the details of each component. 

WOObjectSelector 

Figure 4 shows the layout and keys for 
WOObjectSelector. The component consisLs of a WOPopUpButton 
and two submit buttons within a table. The keys attributeKey, 
displayList. entityName, noS election String and returnPageName 
were mentioned previoLLsly. Their values are pa.ssed into the 
component by it.s parent. 

The other keys, display Attribute, displayObject and 
selectedObject are u.sed IcKally. displayAttribute is a method that 
returns the string for each item displayed in the pop up menu; 
it uses key-value coding to retrieve the string using attributeKey 
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as the key (Listing 1)- 'Hie key displayObject is tlie local 
EOGenericRecord on which the display list iterates and 
selectedObject stores the user’s selection as an EOGenericRecord. 
Implicit in this is that a WO Display Group's array of 
EOGenericRecords, has been bound to dispiayList by the parent. 
The actioas editObjectAttribute and insertNewObject are bound to 
the ‘^Edit" and '^New” buttons, respectively* 


*000 _ A .w 




UteiyiSlltdhiolni _ _ __ _ . 

WDOb^ectSekctcr 

ippttCiUion > 

lession ^ 

AltrlbMi«K«v 
tfliptkvAttnbutff 

diiplavObj«ct 

noS«1«cl(DniStnng 

retUhiPifegcMAFne 

lekctcdObjBet 

•.< 

editObjKlAllnbutt 1 

ln>ermewObJtct ; 

UltSovrct 


Figure 4: Details of WOObjectSelector 


Figure 5 shows the API editor view of WOObjectSelector 
with the five keys that must be bound by a parent 
component. Figure 6 shows how WOObjectSelector is 
embedded in a form element within its parent page, “Main", 
in the demo application, and the bindings implemented 
therein. (Be sure to set up the form for multiple submit 
buttonsj There is only one key declared in Main, namely a 
WODisplayGroup associated with the example application’s 
reference table, called “Country", whose attribute of interest 
is “countr\^''. 

Listings 2 and 3 show the implementation of the actions 
invoked by WOObjectSelector's buttons. Each simply creates 
an instance of the return page using the value bound to 
return Page Name and then invokes takeValueForKey on the 
page to set the values that WOObjectEditor will eventually 
need. As mentioned earlier, every child class of 
WOComponent inherits this key-value coding method. 

There is no custom code for the Main class other than the 
WODisplayGroup variable countryDIsplayGroup, which is 
bound to an entity called Country in the data model for this 
example application. 


YOU'VE GOT YOOO NEW MAC. GREAT. NOW, ALL YOU WANT TO DO 
IS PUOLISH A SIMPLE, YET ELEGANT WEBSITE, CATALOG AND POST YOUR 
PICTURES, DO SOME POBLISRING, DO A LinEE DRAWING, MAKE A LEW 
PDE FILES, ARCRIVE SOME DOCUMENTS 10 SEND TO YOUR MOTHER, CUT 
UP SOME BUTTONS TOO THAI ELEGANT WEBSITE, ANIMATE THEM, 



E 





i IT FOR LESS TRAN 




CftHe' erfFwi' P'iWft PtfllO. Tm^qtwls PffI* SUm® 

DiC?“ row* Stori*' 

SIONElOr ^299 X 

DOWNLOAO NOW OR PORCRASE CO WWW.SIONE.COM 

SXmE SROO * B APPS that set you FREE TO DRAW. TWEAK 
PROCESS AND PliSLJSH YOUR ^OEAS. ON PAPER OR ON THE IVED. 
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Figure 5.' APIEditormew of WOOhfectSekctor 
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Main page. As in WOObjectSeiector, the key displayAttribute is a 
mediod that returns die display string corresponding to tlie 
attribute of objectToEdit that we are updating. 



Figure 1: Deiaik of WOObjectEdikrr 

Figure H dispbys tlte API Editor view of WCWbjectEditor with the 
six keys tfiat must Ix! Ixiund by a fKiteni component. Figure 9 shows 
how WOObjedEditor is embeddtxt in its parent page, "CountryEditor”, 
in tlie demo application and the liinrlings unplernented therein. 
Notice how the Ikxilean values insert!ngNewObject and updatingObject 
are u.sed not only liy WOObjedEditor hut also liy die enclosing page 
itself to vary the prompt depending on the action the user selected. 


Figure 6; WOOhpciSelecior laid out in its parent page 


WOObjectEditor 

Figure 7 sliows the layout and keys for WOObjectEditor. 
d he component consists of two WOConditionals, one for the case 
when die user is updating a record the other for creating a new 
record, Eacli ctjnditional consi.sts of a WOTextField and two 
sul)mit buttons. Four actions are declared in Figure 7, one for 
each of the buttons. Recall Figure 2. Although the component 
has four biitton.s, the user only sees two depending on the 
choice they made from the selector component. 

The keys attribute Key, entity Name, insert! ngNewObject, 
updatingObject and objectToEdit were mentioned earlier. 
WOObjectSelector provicles their valties via the editor component’s 
parent using the aforementioned key-value coding and API 
binding techniques, llie editor's parent component provides the 
value for returnPageName. In our example we simply return to the 
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Figure 8: API Editor mew of WOObjectEditor 
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^^ithout a doubts the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools.” 

- Mac User Magazine Eddy Ajjuards 

"A distinct improvement over Applets ResEdit"" 

— MacTech Magazine 

^Every Mac OS developer should own a copy of Resorcerer'' 

- Leonard Rosenthof Aladdin Systems 

'"Without Resorcerer^ our localization efforts would look like a ^ 

Tower of Babel. Don't do product without it!” 

~ Greg GalanoSf CEO and President, Metrowerks 

'Resorcerer's data template system is amazing." 

— Bill Goodman, author of Smaller Installer and Compact Pro 

'"Resorcerer Rocks! Buy it, you will NOT regret it" 

- Joe Zobkiw, author of A Fragment of Your Imagination 

"'Resorcerer will pay for itself many times over in saved time and effort." 

- Mac User review 

"The template that disassembles RICT's is awesome!" A 

- Bill Steinberg, author ofPyro! and PBTools 

"Resorcerer proved indispensible in its own creation!" 

- Doug McKenna, author of Resorcerer 



# Resorcerer 2 



Version 2.0 



• Very fast, HFS browser for viewing file tree of all volumes 

• Extensibility for new Resorcerer Apprentices (CFM plug-ins) 


new 


• New AppleScript Dictionary (‘aete’) Apprentice Editor 

• MacOS 8 Appearance Manager-savvy Control Editor 

• PowerPlant text traits and menu command support 

• Complete AIFF sound ^le disassembly template 

• Big-, little-, and even mixed-endian template parsing 

• Auto-backup during file saves; folder attribute editing 

• Ships with PowerPC native, fat, and 8SK versions 



Requires System 7.0 or greater 
1.5MB RAM, CD-ROM 


Standard price: $256 (decimal) 
Website price; $128 - $256 
(Educational, quantity, or 
other discounts available) 


Fully supported; it's easier, faster, and more productive than ResEdit 
Safer memory-based, not disk-file-based, design and operation 
All file information and common commands in one easy-to-use window 
Compares resource files, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 
Makes global resource ID or type changes easily and safely 
Builds resource files from simple Rez-like scripts 
Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 
Hot-linking Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

Full integrated support for editing color dialogs and menus 
Try out balloons, 'ictb’s, lists and popups, even create C source code 
Integrated single-window Hex/Code Editor, with patching, searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 


Payment: Check, PC's, or Visa/MC 
Taxes: Colorado customers only 


Extras (call, fax, or email us): 
COD, FedEx, UPS Blue/Red, 
International Shipping 


MATHEM^STHETICS, INC. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 
resorcere r@mathemaestheticsxom 


Tb order by credit card, or to get the latest news, bug fixf^s, uixlates, and apprenticses, visit our website, 


www.mathemaesthetics.com 











Listings 4 and 5 show the implementations for the actions 
insertNewObiact and updateObject. The former creates a new 
instance of the entity specified by entity Name then sets the value 
of the specified attribute using key^value coding. Upon inserting 
the new record into the default editing context, it saves the 
changes. The updateObject method simply sets the new value of 
objectToEdit using key-value coding, then saves the changes. 



Figure 9: WOOhjectEciUor laid out in a 
its parent page. Cotintr^^Editar 


Eniiancemejvts and Improvements 

Our pair of components Ls already very useful and highly 
reusable. However, there are possibilities for improvements. 
One concerns validation and associated exception handling 
as follows: 

The two action methods insertNewObject and 
updateObject have built-in validation rules; as written they each 
enforce a non-null value for every attribute of every entity. This 
may not be unreasonable in the case of reference tal:tles^ but it 
isn’t as flexible as it could be. Moreover, tliere is no exception 
handling for the possibility ihat either insertObject or 
saveChanges fails. These operations could fail for a variety of 
reasons including constraints built in to the data model(s) used 
in a real application. 

There are two obvious alternatives to implementing 
improved validation and exception handling. One is to override 
die method validationFailedWithException in the page that 
encloses WOObjectEditor. Every component inherits this method. 
One w'ould probably implement it in die editor componenfs 
parent liecause the parent knows the context in wdiich validation 


occurs. Another route would l>e to subclass and provide the 
subclass with the required context. 1 probably would choose the 
former path since the context is already known there. 

StmtMARY 

Tills article has illustrated the design and constmction of 
reusable WebObjects components and inter-component 
communicadon using key-value coding. The fully functional 
components discussed herein are widely applicable to the 
maintenance of reference tables, a common situation. 

Bibuography and References 

The interested reader may find the following books useful. 
Of the diree, Ruzek’s book is the best, in my opinion. 
Unfortunately^ it is based on WebObjecLs version 4.5 and 
emphasizes development under Windows. Nevertheless, much is 
applicable and the examples are pretty good. DeMan et al's 
book is based on version 5 and incorporates references to OSX. 
Their discussion of valickition, key-value coding and other 
important topics is very good. However, the book is a hit rough 
around the edges in some places perhaps reflecting its multiple 
audiorship and the need for a bit more editing. Feiler’s hook is 
the least helpful. After a very long (60 pages) and general 
introduaion, the book finally gets around to discussing 
OpenBase. for many topics tlie author merely recapitulates 
Apple's documentation, for others he provides only the most 
cursoiy treatment and no concrete examples. 

* DeMan, Michael, Frederico, Gustavo, et. al. Professional 
WebObjects 5 0 with Java, Wrox Press Ltd.^ Birmingham, UK, 
2001 , 

* Ruzek, George, WehOhJecis Web Applicatum Dei^eiopment 
Kit, Sams Publishing, Indianap^ilis, 2001 

* Feiler, Jesse, Building WebObjects 5 Applications, McGraw- 
Hill/Osbome, Berkeley, 2002, 


listiiig J: WQO bjeciS elec tOfjava _ 

displayAttribuie 


public String dlsplayAttribute{)i 

return (String] dispIayObJect.valueForKey(attributeKey): 


Listing 2: WOObjecrtSrfedtqrjava_ _ 

editObjectAttributc 

public WOConiponent editObjectAttributeO f 

r 

Tlie user needs to select some value to edit; 
i/ not, do nothing. 

V 

if fselectedObject = null] return null; 

WOComponent nextPage = 

(VOCoinponent) pageWithName (returoPageNamc); 
nextPage .takeValueForitey C^ntityName»’“entltyNaiie"): 
nextPage, takeValueForKey [selectedObject. “objectToEdit") ; 
nextPage.takeValueForKey(attributeKey."attributeKey"): 
nextPage.takeValueForKey(Boolean.TRUE.“updatlngObj ect"J:\ 
nextPage.takeValuePorKey(Boolean.FALSE. 

^'insertingNewObject"] i 

return nextPage: 
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Be productive. Stay productive. 

Introducing FastTrack Schedule B. Redesigned for Mac OS X and packed with new productivity features and a bold Aqua 
Interface-FastTrack Schedule 8 has alf the tools you need to ensure projea success. For a tree demo version or to order, 
call us today at 300,450.1983. 
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inscrlNcwObjcct 



Fetch 


public WOGomponeut insertKewObjectO[ 

WOComponeat nextPage = 

(WOCoDiponent J paaeWithNaiiie{ returnPagaName): 
nextPage, takeValueForKey (entityName, '*entityNaate"}: 
nextPage.takeValueForKeyCnull, ^-objectToEdit"); 
nextPaga.takeValueForKey(attributsKeyH"attributeKey"): 
nextPage, t akeValueFo rXey (Boolean * FALSE * ''updatingOb ject"}: 
nextPage.takeValueForKey(Boolean.TRUE, 

^InsertingKewObject"): 

return nextPage: 


public WOComponent InsertNevObjECtO I 
if (displayAttributei=null 

displayAttribute.length()>0)f 

r 

the user has eniered a nun-blank string; 
create a new objea 
7 


inscriNcwObject 


EOClassDescription descrlptioa = 

EOClassDescriptlon.ciassDescrlptionForEntityName( 

entityHameJi 

EOEoterprlseObject nevObJect = 

description * createlnstanceWitbEditingContext[null * 

null): 

uevObj ect,takeValueForKey(displayAtt ribute * 

attrlbuteKey); 

EOEditingConext dec ^ 

this.session(],defaultEditingContext(); 
dec.insertobject(newObject); 
dec^saveChangesO: 


WOConiponent nextPage = 

(WOComponent J pageWithfJaaGCreturnPageHaine): 
return nextPage: 

1 


Mac s best friend. 


Listiag 5: WOObjeclEdltor.java _ 

updateObject 

public WOCortponent updateObject () I 
if [displayAttributGl"null 

displayAttribute.length()>0)[ 

// the user has entered a nun-blank string 
objeetToEdit.takeValueForKey(displayAttribute, 

attributeKey); 

this.session 0.defaultEditingContextO,BaveCbanges(); 

] 

WOComponent nextPage = 

(WOComponent)pageWlthName CreturnPageName): 
return nextPage; 


Fetchsoftworks.com 

Version 4.0.2 now available. 
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MAC OS X 


By - Andretv C. Stone 


Takes All Sorts 


Make Your TableViews Autosort! 


One of the coolest pieces of object technology in the 
Cocoa bag of tricks is the NSTableView, and its daughter, 
NSOutlineView. The tableView lets you display a list of 
items with various properties. As in a spreadsheet, it 
displays rows of information - anything from simpie text 
to graphics or even quick time movies! Once you learn 
the fundamentals of the tableView and the outline View, 
they’ll quickly become some of your favorite user 
interface objects. 

This article will take the NSTableView further, and 
show^ ycju how to add “auto sort” to your tableView, and 
the objects it represents. It assumes you have read the 
documentation for NSTableView^ and its companion class 
NSTableColumn and perhaps already have an app w^ith an 
NSTableView of your own. You can try out this sort idea 
in Apple's Mail. A Mail Box shows a tableView of the list 
of messages, sender, subject, date, size, etc: 



Figure 1. You ca n play with quick sort feature in 
Apple's xMail application, 


When you click on the title cell of a column, an arrow 
appears to show direction of the sort, the ceil is 
highlighted, and the messages are sorted on that key. If 
you click the title cell of that same column again, it toggles 
the sort to reverse its direction: if it was an ascending sort, 
now it’s a descending sort. Sorting mail by subject is 
particularly interesting for deleting spam en masse! 


When Time Equais Money,,, 

When preparing TimeEquals Money 2.0 

<http://www.5tone,conn/TimeEqualsMoney/> this spring, t decided 
users would love to be able to sort tJieir time and expense 
entries on any key, in either direction with a simple click. So I 
reread the documentation Apple provides on the NSTalMeView 
class. I highly recommend actually reading the .h files! Ifs 
ainazing how much saiff is already anticipated for you! There is 
a delegate method, - (void) tableView :(NSTabl€View*)tv 
didCiIickTableCoIumn:(NSTalileCk>lumn ’)tableColumn. So, it 
seemed, I simply had to implement tliis metliod in my 
NSWmdowQjntroller subckss, which Ls arciiitecturally a sound 
cht]ice ibr tlie NSTableView delegate. T low^ever, die mediod was 
simply not being called when I clicked on die column header 
cell. It turns out, and 1 noted this heavily in my code, diat T 
neither column reodering nor column selecdon is selected in 
Interface Builder’s NSTableView inspector, then die method Is 
not calltxi. Turning on column reordering was a simple fix and 
a desired feaaire! You can, of course, also call one of these 
methods programmatically with a pammeter of YES: 

(void)GGtAllowsColumnReordering:(BOOL)flag: 

- (void)setAllowsColumnSelection:(BOOL)flag: 

Following on the Model-View-ControHer pattern that 1 
have discussed in previous articles on Cocoa architecture, 
I decided to store the sort column, and Its direction in my 
NSDocument subclass, as well as make it responsible for 
the sorting of its items. This way, you can undo the sort, 
automatically mark die document as unsaved as well as 
save die sort between sessions. The user clicks the 
tableView column header, the window controller then sets 
the document's sort key, or direction if the key was 
already set to that column. Then the document tells itself 
to sort, which tells its NSMutableArray of entries to sort its 
contents. Finally, the document tells its window 
controllers to reload the tableView, which updates the 
interface to display the new sort order: 


Andrew Stone, aiidrew@stone.coni. is Cliief Chef at Stone Design, http://ww^^stone.com, has this to say about Cocoa and Stone Studio with all due 
respect to Gary Snyder’s Turtle Island, “It’s objects all the way down" . 
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Figure 2. This fable View lets you click a column header 
to son on fhal key - up or down. 

Model Behavior 

The implementation of the actual sort is trivial- just ask 
the list to sort itself based on asking its elements to sort using 
a selector: Hist sortUsingSelector:@selector(compare;)l; 

During the list’s sorting procedure, it repeatedly calls, in 
this case, compare: on one list item against anothen 

1 like to just reuse the Kit’s compare: which is 
implemented in NSString, NSDate, NSCell, NSValue, etc: 

- (NS CompsrlsonResult)compare;(Id)other: 

The NSComparlsoiiResult has these three values: 
NSOrderedAscending “ -I, NSOrderedSanie - 0, 

NSOrderedDescending = 1. Since so many objects reply 
to compare:, you might implement it something like this 
in your data object, given that the sort key is the same 
string as the column identifiers, and you have various 
numbers, dales, strings and even booleans: 

// the Data MODEL - the document has a list of these entities: 

^interface Piecework : NSObject <NSCopying> 

[ 

NSCalendarDate *atartTime: 

NSString ^description; 

NSTimeInterval timeOnJob; 
float _rate: 

BOOL paid; 
id owner; 

i ’ ' 

- (NSComparisonResult)compare;(Id)other: 
(void)BetOwner:Cid)DwnsMe: 

- (NSCalendarDate *)startTime: 

- (NSTimeTnterval)timeOnJob; 

- (NSString *)workDescriptlon; 

- (float) EotitsOii Job : 

- (float)rate; 

- (EOOL)paid; 

@Gnd 

©implementation Piecework 


• {NSComparisonResult}compare:(id)other t 

BOOL IsDescending = [owner sortIsDescending]; 
NSString *key = [owner sortColumn]: 

// now determine which one is Orst based on son direction: 

Piecework *f±rEt = laDescendlng ? other : self; 
if (first == other) other = self: 

if {[key IsEqualToStrlTig ;@''T±meOnJob"] ) 1 

return [[NSKumber numberWlthFloat:[other 
timeOnJob]] compare: [NSNumber 
numberWlthFloat:[first timeOnJob]]]: 


I else if {[key isEqualToStriug:@"Date"] ) ! 

return [[other startTlme] compare; [first 
startTlme]]: 

[ else if C [key 

isEquaiToString:@"Description”1) i 
ii Very^ handy macro: 

//define IS_NULL(s) (Is || [s isEqualToString:@'"'l ) 
if {IS_NULL([other workDescription] ) ) 
return NSOrderedDescending: 

if (IS_NULL( [first workDescription] )) 
return NSOrderedAscending; 

if people prefer upper and lower case mixed, unlike UNIX: 

return [[other workDescription] 
caselnsensitiveCompare;[first workDescription] ] : 

! else if ([key isEqualToString:©"Paid"] ) f 
return [[NSNumber numberWlthBool;[other 
paid]] compare:[NSNumber numberWithBool: [first 
paid]]]; 

3 

return 0; 

1 

©end 


Here are the relevant instant variables and methods in 
the NSDocument subclass: 

©interface HyDocument ; NSDocument [ 

NSMutahleArray ’‘^workLlst: 

NSString *_sortColumn; 

BOOL _sortIsDescending: 

i 

- (void)sort; 

’ (NSArray ‘)workList: 

- (void)setSortColumn;(NSString ')identifier; 

- (NSString ^)sort Column; 

■ (void)set3ortIaDescending;(BOOL)whichWay; 

■ (BOOL)sortlsDeacending; 

©end 

©implementation MyDocument 


fvoid)sort:(NSMutab1eArray *)llst I 
[list 

makeObj ectsPerforraSolocton©selector(setOwner:) 
withObject:se1f]; 

[list sortUsingSelector:©selector(compare 0] ; 

// asks us for how It 

1 

- (void) sort I 

if (NOT„NULL(_sortColumn)) I 
[self sort:_workL±st]: 

[[self windowGontrollers] 

makeObj ectsPerformSelector:©selector(updateTotalsAnd 
Reload)]: 

I 

] 

' (void)setSortColumn:(NSString ‘)identlfler I 

if {I[identifier isEqualToStrlng:_sortColumn]) 

[ 

[[[self undoManager] 
prepareWithlnvocationTarget:seIf ] 
setSortColumn:_sortColumn]; 

[_sortColumn release]; 

_EortColumn “ [Identifier copyWithZone :[ self 
zone]]; 

[[self undoManager] 

setActlonNameiNSLocaiiaedStringFromTable(©"Sort”.©“T 
imeCardtitle of undo the sort action”)]; 

1 

} 

- (NSString *) BortGolutnn j 

return _sortColumn: 

} 
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Collection Includes: 


Save thousands by reducing 
coding and testing time 

Spend your time developing 
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software stand out 


Rotational Slider 

Formatters for Currency, Phone, 
Text, and Custom Fields 
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Visit Jiiva's wet^ ite 

turn text fields into clickable URLs 


Quickly create professional 
looking applications 

Utilize object-oriented 
technology for easy 
customization and reuse 

No deployment licenses or 
royalties! 


Calendar View and Popup _ _ 

Show Advanced Options j 

URL Clickable Field 
Twiddle View 
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- (void)setSortl^Descending:(BOOL)whichWay J 

if (whlchWay 1= _sortIsDescending) t 
[[[self undoManager] 
prepareWithlnvocatlonTarget:self] 
setSottlsDescending:_SDrtlsDescending]: 
_sortIsDescending = wbichWay: 

I [self undoManager] 

setActlonName : NSLocalizedSt rlngFromTable Sort 

DlreGtlon'\@”TimeCard"♦©"title of undo tbe sort up 
or down action")]: 

] 

- (BOOL) sortIsDescending [ 

return _sortIsDescendlngi 

1 

- (NSArray ‘)workLlst [ return _workLiBt; ] 

- (void)setWorkList:{NSMutfibleArray *)list { 

[[[self undoManager] 
prepareWlthlnvocationTarget:self] 
setWorkList:_workList]' 

[_workList release]j 

if (N0T_N0LL(_sortColumn)) [self sort;list]: 
„workList = [list tnutableCopyWithZone: [self 
zone]] ; 

[_workLlst 

makeObJectsFerfonnSelectort©selector(setOwner:) 
withObject:self] i 

[[self wlndowControllers] 

makeOb jectsPerformSelector :©selector (iipdateTotalsAnd 
Reload)]; 

[[self undoKanagerl 

setActionffame ♦NSLocalizedStringFromTable C@”Work 
Change'*. @'*TlmeCard" . ©"Action name for changing 
worklist")] i 
! 

// And don't forget to actually archive and read the sort info 
// I highly recommended using human readable XML dictionaries; 

- (NSMutableDlctlonary ‘) workDocuinentDictionary I 

NSMutableDlctionary ’doc = [NSMutableDictionary 
dictionary]: 

unsigned i* c " [_workList count]; 

If (NOT_NULL(_aortColumn)} [doc 
setObject;_sortColumn forKey;SortNameKey]; 

if C_sortIaDescending) [doc 
setObJect;©"YES" forKey:SortDescendingKey] ; 

return doc; 


* (BOOL)loadDataRepresentation;(NSData *)data 
ofType: 

(NSString *)type t 

if ( [type isEqualToString!DocumentType] ) [ 

NSDictlonary *doc = [self 
workDocumentDlctIonaryFromData:data]: 
id obj; 

obj = [doc objectForKey;SortNameKey]: 
if (obj) { 

[self setSortColumn;obj]: 

1 

obj = [doc ohjectForKey;SortDescendingKey]: 
if (obj) i 

_sortlsEescending = [©"YES** 
isEqualToStting:obj] ; 

) 

return YES; 

) 

return NO; 

) 

©end 


Control Freak 

Finally, we come to the meat of the matter in our 
NSWindowConrroller subclass which is our 
NSTableView's dataSource as well as delegate, 

©interface JobWindqvController : NSWindowController 

f 

IBOutlet NSTabieView 'tableView; 

NSimage ’descendlngSortinglmage; 

NSImage *ascendlng3ortlnglinage: 

1 

We have work to do in our window initialization 
method that gets called when the Interface has loaded, 
awakeFromNib* We want to get the images that we shall 
display when a sort is made^ Using class-dump as 
described in my iPhoio Exporter bundle article 
<http://www.omnigroup.com/'-nygard/Projects/inclex.html>, you 
might note that there are hidden, private Apple internal 
API to access the images to indicate ascending or 
descending sorts! Since one should absolutely never rely 
on hidden API to not dissolve into the ether in 
subsequent system releases, always bracket the use of 
these methods with a “respondsToSelector:"' query, and 
provide backup images of your own: 

- (void)awakeFromNib 

[ 

// private images: 

If ([[NSTabieView class] 

respondsToSelector:©selector[_defaultTableHeaderSort 
Image) ] ) 

ascendlngSortingiraage ^ [[NSTabieView class] 
_defaultTBbleHeaderSortimage]; 

else ascendingSortinglmage = [[NSImage 
imageNamed :©"asceTidingSort"] retain] ; 

if ([[NSTabieView class] 

reapondsToSelectur:©selecrot[_defaultTableHeaderReve 
rseSortImage)]) 

desceudingSortingIraage = [ [NSTabieView class] 

_ilefaultTableHeaderReverseSortImage] : 

else descendlngSortinglmage = [[NSImage 
imageNamed:@"desc€ndingSort"] retain] : 

i' 

If you ullow users to tnove and resize columns, then 
you definitely want to additionaly call these two methods in 
awakeFromNib - this will reestablLsh tlieir preferences and 
give the system a name to .save tlie column order and sizes. 

[tableView setAutosaveTableColumns:YES]; 
[tableView setAutOsaveNaraei^^WorkTable"]; 

So, now we Ye ready to implement the delegate method 
which gets called when the column title cell is clicked. The 
one fine point is that we want to make a note of which item 
was selected before the sort, so we can reselect it after the 
sort (its row number may have changed after the sort). We 
ask the tableView if it already has an image in that column, 
thus indicating that we need to toggle the direction, 
otherwise, well set the new sort key. The actual work of 
setting up the tableViewY header lillighting is done in 
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updateTableHeaderToMatchCurrentSort, This is factored 
into a separate method so we can also call it when loading 
a document to restore last saved sort state. 

// BIG COCOA NOTE: jf coluimi reordering or coJumn selection is not 
on 

// then this doesn’t get calledl! 

(void) tableView:(NSTableView*)tV 
dldClickTableColumn: (NSTableColumn * ) tableColtimn ] 
KSImage *sortOrderlmage — [tv 
indicat orlmagelnTableColupin : tableColuniTi] ; 

NSStrlng *c:olumnKGy ” [tableColumn identifier] : 
My Document *doc = [self document]: 

Piecework *work = [aelf aelectedWork] ; 

// If the user clicked the column which already has the sort indicator 
// then just flip the sort order. 

if (sortOrderIniagc [ \ columnKey = [doc 
SortColumn]) [ 

[doc aetSortlaDcscending:1[doc 
sortIsDescending]]: 
t else [ 

[doc setSortColumnicolumnKoy]: 

[ 

[self updateTableHeaderToMatchCurrentSort]; 

// now do ii * doc calls us back when done 
[doc sort] : 

// bm reseicct the one previously selected: 

if (work) [self aelectWork:work]: 


This method updates the state of the NSTableColumn 
by first clearing all cells, and then setting the correct 
image and hiiighting on the column to sort by, if any: 

(void.) updateTableHeaderToMatcbCurrentSort ] 

BOOL iaDescetiding - [ [self document] 
sortlsDescending] ; 

NSString ’‘key “ [ [self document] sortColumn] : 
tJSArray *a = [tableVlev tableColumns] : 
NSTableColumn ^column = [tableView 
tableCotumnWlthldentifierikey]: 
unsigned 1 ” [a count]; 

while (i— > 0) [tableVlew setIndicatorlmage:nil 
inTableColumn:[a objectAtIndex;i]]; 

if (NOT_NULL{key)) f 

[tableView aetlndicatorlmage: (iaDescendltig 
7 as c endingSortinglma ge:d es cendlngSo rtinglmage) 
inTableColumntcolumn]: 

[tableView 

setHlghlightedTableColumn:column]: 

1 else [tableView 
s etHighllghtedTableCa luimn : nil] : 

1 

And our helper functions to make the code neat and 
compact: 

- (NSArray ‘)workList I 

return [[self document] workLlst]: 

[ 

(VO id)updataTotalsAndReload [ 

// other ui: 

// [ sti f updateToisil s |; 

[tableView reloadData]: 

- tFieceWork *)selectedWork [ 

NSArray “workLiat ^ [self workList]: 

Int row = [tableView selectedRow]: 
if (row > -1 £i6i row < [workList count]) return 
[workList objactAtindex:row]; 
return nil: 


S 

- (void)selectWork:(Piecework *)work I 
NSArray *a = [self workLlst]: 
unsigned i = [a indexOfObject:work]: 
if (.i 1= NSNotFound) [self aelectRow: 1] ; 


Devil in the Details 

So, now we got sorting working, what sort of 
problems might we rim into? Let’s say a user edits the 
field of an entry in the sorted column. Upon fhiishing 
editing, they may have changed the relative order of that 
entry, requiring a new sort, and a reloading of the 
tableView again! We can check if have the sorted 
column wdien the data gets set in 
tableView ;setObjectVal ue: forTableCol u mn: row: 

- (void)tableView:{NSTableView •)tv 
setObjectValue:(id)object 

forTableColumn:(NSTableColumn *)tc row:(int)row; 

[ 

NSArray *workList = [self workLiat]: 
NSString *ldent =" [tc identifier] : 
if (tv tableView) ( 

Piecework *work ~ [workList 
objectAt Index:row]: 

if ( [Ident isEqual: ®"Description*']) ( 

[work setWorkDescriptlon:object]; 
[self sort IfSortedOn:ident 

work:work); 

1 else if .... 

1 


Isnl the devil in the details? Because the tableView 
will want to “select next” after setOlijectValue: is called, 
the wrong row might be selected if the sort changed the 
currently selected item's row. liy calling this method, 
well first end editing on the tableView^ .so any inadvertent 
select next is foiled. Note the delay of 0.0 .seconds which 
means to schedule the call of the method after the current 
event loop finishes: 

- (void)afterSort:[Piecework *)work ] 

[[self window] makeFl rstRes porid(5r : [ self 
window]]: 

[seif selectWork:work]: 
f 

- (void)sortIfSortedOn:(NSString *)ldent 
work:(Piecework *)work ( 

if ([[[self document] sortColumn] 
isEqualToString:ident]) \ 

int aldPosltion 

[[self window) makeFirstResponder:[self 

window]]: 

[[self document] sort]; 

[self performSelector:@selGCtor(afterSort:) 
withObject:work afterDelay:0.0] ; 

1 else [self updateTotalsAndReload]; 

] 


Conclusion 

Sorting is something users expect table Views to do 
now - and with a little effort, all of your tableViews can 
son themselves! 
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OmniObjectMeter has not been tested on blowfish 
allergies, but It is the best tool to help you seek and 
destroy memory leaks and expensive allocation 
operations In your Cocoa programs. 

• Track allocations, references, and deallocations of 
Objecttve-C, CoreFoundatlon, and BSD objects In a 
running process. 

• Use our unique matching window to quickly match and 
hide paired reference count changing events. All that 
Will be left are leaks, zombies, and retain cycles. 

• Track down and eliminate transient objects, excessive 
autoreleases, and other Inefficient operations. 


dstthplairiing ^ 

of cofi^rant swapping ? ^ 

Do jiiAM manufactu fcrs - 
send ymrbirthday cards? 

Muhensf^ ^ 

terabyte iAiacs? 


discuss 
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- But wait, 

OmniCraffle 2.0 


THERE'S MORE - 

OMNIOUTLINER 2.0 


Our symbolic drawing application easily generates flow charts, ER models, 
network diagrams, and much more. We think it's the bee's knees. And 
being the overachieving developers that we are, we went and added some 
cool features to OmnlCraffle that make our programming lives easier. Now 
with 2.0 we're sharing them with the world, so your life will be easier too. 
Aren't we Just peachy that way? 


Project Builder / Framework Import: drag in a Cocoa 
project or framework to automatically create a class 
hierarchy diagram with clickable links to header files. 

AppleScript Everywhere : use OmnlCraffle as an 
Interface for tasks like bug tracking and scheduling. 
Attach scripts to graphics to make interactive documents; 
Import and layout data from scriptable applications like 
FileMaker. 



OmniOutllner Is a general-purpose outlining and list¬ 
making program; we've found it has myriad uses In 
software development: bug lists, projea schedules, 
pseudocode outlines, etc. Plus a 
few features just for geeks like us: 

“Sample” Import : presents output from 
Apple's command-line "sample" progranrt 
(a useful performance monitoring tool) In 
an easy-to-read hierarchical view, (just 
remove the ‘.ixt* extension from the 
output file and open it in OmniOutliner.) 


More AppleScript: 2.0 adds complete AppleScript support, so, for 
example, you can dump your project schedule to OmniCraffle. 



If you've bought a Power Met or PowerBook since January 20Q2. you’re already sitting in the back of the bus with the cool kids — OmnlCraffle 1.1 and OmniOuttiner 1.2 are already 
Installed in your Applications folder. But drop by our website and upgrade to the 2,0 versions we talk about here: theVrc much cooler. 

Q www.omnigroup.com/mactech 

^ 7 " The Omni Group 
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REVIEW 


By Bradley Kaldahl and Jacob Kirk 


Macromedia Flash; Visual vs. Language- 
Based programming 


Macromedia Flash has taken the web by storm and with it a 
new programming paradigm has evolved that we refer to as 
""Visual Programming.” Non-traditional “Visual Programmers" are 
producing algorithms that are really quite intriguing. In some 
respects this new visual paradigm represents an opponunity to 
create algorithms based on visual logic, which is an interesting 
alternative to traditional language-based algorithms. Please read 
on to see If you agree. 

In the traditional language-based programming paradigm, 
the developer relies almost completely on the programming code 
to accomplish the desired task. While several highly respected 
authors such as Grady Booch and Coad & Yourdon have created 
visual diagram-based models for 00 development, ultimately the 
design is translated into code. On the other hand Flash allows 
both design and implementation in a visual environment. This 
visual style of programming obviously has a strong appeal to 
certain individuals, most notably creatives, designers, and those 
unfamiliar with traditional programming languages and 
conventions. 

Any programmer called upon to work or consult on an 
Action Script project should be aware of the issues and 
idiosyncrasies of this new trend in “Visual Programming" as they 
will likely encounter legacy code that has been developed using 
the visual paradigm. 

Problem definition 

To contrast the visual paradigm with the language-based 
approach we have defined a simple programming problem. 

Using Macromedia Flash 5, animate an object to move 
across the stage. When the user rolls-over tlie object have it 
reverse direction. 


If you are familiar with Flash and ActionScript then we hope 
that you will enjoy the contrast of these two disparate 
techniques. If you are new to ActionScript we hope you will 
benefit from our discussion of some of the programming 
anomalies you will encounter in Flash when using the language- 
based approach. 

Anomalies in ActionScript 

While ActionScript resembles JavaScript, it is helpful to 
remember that ActionScript must conform to the animation and 
encapsulation features found in Flash. One of the more 
noticeable programming differences you will encounter in Flash 
is that you cannot animate an object using a standard FOE or 
WHILE repeat loop. There has been some debate as to why this 
is the case. Some have .suggested that it is because the computer 
can execute a repeal loop at a much faster rate than the screen 
can redraw. While on the surface this sounds plausible, it 
suggests that computer animation within a repeat loop cannot be 
accomplished. According to Michael Williams, Associate Product 
Manager at Macromedia: 'The issue here is not the fact that FOR 
and WHILE execute too quickly, it is because ActionScript, on a 
frame, executes before the stage is updated. The stage is only 
updated after all scripts on that frame have been executed." 

If you do attempt to use the FOE or WHILE repeat loop for 
animation you will most likely encounter the following alert. 



Figure 1. Flash places a 15 second Hme-out limit 
on FOR and WHILE repeal loops. 


Bradley Kaldahl is a professor of Computer Publishing at Montgomery College and is author of the hook EZ Flash 5. You can contact him 
through www.hotFlashBook.com 

Jacob Kirk is a Designer, Teacher, Author and an aU around Interactive Web "'Whiz-kid L He specializes in using Macromedia Flash and Adobe 
liveMotion. More information about what Jacob is up to can be found at www.EmazingMedia.com. 
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Mr Williams explains; “The Flash Player itself provides 
this option to abort the script. The Flash Player will do this 
when it plays a movie which contains a one-frame 
ActionScript loop which can repeat itself indefinitely or for 
too long. A movie with such a ioop can tax the resources of 
the computer system playing it. Giving viewers the option to 
end the script helps the Flash Player prevent an SWF file 
from freezing the viewer's browser or system. To avoid 
creating a movie that triggers this error message when it is 
played in the Flash Player, create a loop that goes through 
frames. You can do this by evaluating a variable in an if 
statement and, if the variable conditionalizes as true, then 
have the movie break the loop by going to the next frame. If 
the variable does not conditionalize as true, then have the 
movie loop back to the first frame (usually two ro three 
frames back) of the movie.” 

The question still remains: How can an object be 
animated and controlled with ActionScript? 

As discussed by Mr. Williams: ''Use ActionScript applied 
to a Movie Clip, also known as clipEvents. For example, you 
have a raovieClip on stage named “circle'' the following code 
will move the circle across the X axis 10 pixels once per 
frame: 

onCllpEvent (enterFranie) { 

_x +- 10: 

1 

This is dependent on the frame rate of the movie. In the 
default case this will refresh 12 frames/sec, but this can be 
increased or decreased by changing the movies frame rate at 
authortime.” 


The Language-Based SoLunoN 


PsuedoCode 

Move the object by I S pixels per frame. 

If the object goes off the left edge of the stage 

then place the object on the right side of the stage. 
If the object goes off the right side of the stage 
then place the object on the left aide of the stage. 

When the user rolls-over the object 
stop the object from moving. 

When the user rolls-off the object 
reverse the direction of the object. 


Mov ic Clip Scr ipt __ 

Animate and wrap object. 
r onClipEventCload) is being used to define some of the varjables, 

The variable move Amount is the number of pixels the object will be 
animated. 

ballLoc: (ball location) is used to define tlic location of the center point of 
the movieClip that encapsulates the ball-Button object. 

_parcnt: is a relative reference to the movieClip that encapsulates the ball 
object.*/ 


onClipEvent (load) [ 
moveAtnount “ 15; 
ballLoc = ^parent 
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r The (enterFrame) clipEveni is the animation repeat loop used by- Flash. 
ballLoc._x += moveAmount will move the obfect by the move Amount each 
lime a new frame is called. The two IF statements (with the magic numbers) 
are checking to see if the object has exceeded the left or right edge of the 
stage. They are set to create an object wrap so the object appears to leave 
one edge and return on the opposite edge of the stage. V 

onClipEvent (enterFrame) { 
ballLoc._x += moveAmount; 

If {ballLoc*_x>640) [ 

ballLoc,_x “ 0; 

f 

if (ballLoc»_x<0) [ 

ballLoc._x ” 640: 

I 

I 


li sting 2; Lan g uage-Based object Script 

Reverse ob]^i direction. 
/• This script is placed inside a button object on the stage. 

Both rollQvcr and rollout use the this, reference which insures that only the 
object that received the event will have its variables altered. If multiple 
instances of the ball object were used without the tliis. parameter ail the 
objects on the stage wfjuld reverse direction. storePosiiion is a global 
variable created on the fly. h holds the original moveAmount before 
temporarily setting the moveAmount to 0 to stop the object. rollOut 
restores the original moveAmount, then reverses the directioo of the object 
by setting it to the opposite of its original value, 7 

on (rollOver) I 

this * storeFosition^moveAmount: 

this, rQoveAnioUTit=0; 

j 

on (rollout) I 

this.moveAmount “ storePoeition: 

this .moveAinount “ jUiOveAmount **1: 

I 

Since the programmer has taken control of the objecl 
with ActionScript, knowledge of the timeline is not needed. 
This animation takes place on a single frame. However, the 
developer does need to know how to create a button symbol 
since it is the only object that will respond to a rohOver 
event. Additionally the developer needs to know how to 
encapsulate the button in a movieClip symbol, since it is the 
only object that will accept a clipEvent. 

In contrast the visual solution, presented below, utilizes 
the Flash timeline and its tweening capabilities to create the 
movement. The animation capabilities of Flash simplify the 
scripting. 

The Visual Solution 

Some might refer to the visual solution as a ''designers 
approach” or a “non-programmers” solution, but to minimize 
it would be inappropriaie as it demonstrates many of the 
features that programmers strive for when creating an 
algorithm. U is simple, elegant, fast and responsive, and with 
Flashs built-in encapsulation capabilities, it is easily reusable, 
Bradley Kaldahl refers to the visual algorithm presented 
below as “Equal Parallel Inverse Animation’s," or EPL 


Description of the visual solution 

Frame if Frame # 

1--—40 • 100--140** 

»»>»»»»» «««««<« 

Animate Left to Right Animate right to left 
• “ Script to loop hack to frame 1 
‘ = Script to loop back to frame 100 

The object is animated to move from left to right (frame 
1-40) using a motion tween. In frame 1 the object is on the 
LEFT side of the stage and in frame 40 the object is on the 
far RIGHT When the animation playback-head reaches frame 
40 it loops back to frame 1 using a simple “gotoAndPlay” 
navigation script placed on the timeline. An equal inverse 
animation is created further out on the timeline, in which the 
object is animated from right to left (frame 100-140), In frame 
100 the object is on the RIGHT side of the stage and in frame 
140 the object is on the LEFT. The two animation’s are on the 
same timeline but move in opposite directions as shown in 
Figure 2. 


Repeat Loop Repeat Loop 

gQtQAr>dPlay(1); gotoAndPlay(1(K5); 


Motion Tween IVtotion Tween 

Object movaslieft to righl Objacr moves right to left 



Figure 2, The Animation Timeline 


When the animation begins, the playback head is looping 
from frame 1-40, i.e., the object is moving from left to right. To 
capture the rollOver event and jump the playback-head to the 
inverse animation another simple navigation script is placed 
inside the object. 

On Rollover 

gotoAudPley fratne (x of the inverse animation) 

End RollOver 

It is important to note that Uiere are two separate 
instances of the ball object shown in figure 2 above. 
Each instance of the ball object can have a different 
script. The first instance begins on frame 1, and the 
second instance begins on frame 100. (Technically 
speaking there are actually 4 instances of the ball 
because each keyframe on the timeline represents an 
instance. Frame 40 and frame 140 both display a one 
frame instance of the ball object. For the sake of 
discussion we will refer to the first animation as instance 
one and the second animation as instance two). To 
view the code in the first instance of the ball object you 
would click on frame 1 on the timeline then click on the 
ball object on the stage. To view the code in the second 
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One Shot 


360 One VR 

The 360 One is an amazing product that captures a complete 
360® panoramic image in a single camera shot. The system is the 
perfect solution for capturing all the action, as it happens I Years of 
extensive research have produced an innovative solution that 
creates an immersive image without the restrictions or 
compromises normally associated with panoramic photography* 

The system consists of a lightweight and rugged proprietary optical device and 
the irmovative FhotoWarp'^'^ software from EyeSee 360, The unique mirrored 
optic provides a complete 360® horizontal coverage with an outstanding 100® 
vertical field-of-view (50® above and 50® below the horizon). 
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The optic has a 
standard 67mm 
thread mount and can 
be adapted to a 
number of cameras 
using either Kaidan 
camera specific 
mounting kits or 
commercially 
available step-up 
rings that fit your 
camera. For a 
complete list of 
supported cameras 
and kits, please visit 
the 360 One VR web 
site. 


No Limits! 


^ Vertical 
100” Field 
of View 

I 

/ 


360® 

image 


The 360 One VR is available with a variety of photographic 
accessories. These include: monopods, tripods, bubble levels, camera 
bags and Pelican hard cases* You can purchase them separately or 
together at a discount in either our Fro Accessory or Real Estate Kit for 
the 360 One VR, 

For more information on camera mounting kits and all the latest 
accessories, visit our website, 




http://www,360OneVR,com 


Kaidan Incorporated 

703 East Pennsylvania Blvd, Feasterville, PA 19053, USA 
Phone: 215-364-1778 * Fax; 215-322-4186 • info@kaidan*com 



http:// WWW, ka i da n, c o m 


EyeSee360“ 


http://WWW, ey esee360,com 


Kaidan is a tfademank of Kaidan Incoqjorated. EyeSeelfiO and Photo Warp arc registered Itadeinarks of EyeSee360 Inc. 360 One VR is a trademark of EyeSee360 and Kaidan 
Incorporated. QuickTime and Mac OS X arc registered trademarks of Apple Computei^ Inc, Windows is a registered trademark of Microsoft Corporation. Coolpix is a registered 
trademark of Nikon, Inc. Java is a trademark of Sun Microsystems. All other tradeiiiarks are the property of their respective owners. Specifications and equipment are subject to change 
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instance of the ball object, click on frame 100 on the 
timeline then click on the ball object on the stage. 

The final question is; Which frame in the inverse 
animation will produce a smooth reverse? 

Algorithm - Equal Parallel Inverse Animation's 
with Flash 

Flash provides an easy-to-use property called 
_currentFrame, which provides the number of the 
frame when the event occurs. Using this property the 
following algorithm finds the inverse frame in the 
reverse animation. 

Inverse of first the first animation instance = 
Number of Frames in the Animation - Current 
Frame Number + Distance to the Reverse 
Animation or (NFA - CFN + D2RA = Inverse). 

Inverse of the second animation instance = 
Distance to the Reverse Animation - Current Frame 
Number + Number of Frames in the Animation or 
(D2RA - CFN + NFA = Inverse). 

For example, using figure 2 and discussion above, if 
the user rolled over the object while it was on frame 
23... NFA{4D) - CFN(23) + D2KA(100) = Frame 
number T17. 

By jumping the playback head to frame 117 the object 
appears unchanged with the exception of reversing 
direction of movement. 

Listing 1: Visual Solution, first animation 
tlmelifie loop script 

Ptaced in frame 4Q of the Unieline 

gotoAiidPlay (1); 

Listing 2: Visual Solution, second animation 
timeline Joop script 

Placed in frame 140 of the timeline 

gotoAndPlay (100): 

Listing 3: Visual Solution, first object instance 

script _ _ 

Placed in the first imstance of the object 
//The Number of Frames in the Animation = 40: 

// Distance to the Reverse Animation - 100; 


Listing 4: Visual Solution, second object instance 
script ___ _ 

Placed in the second instance of the object 

on (rollover) { 
stop (): 

} 

on (rollout) { 

gotoAndPlay (LOO - _ciurr entframe + 40 ) : 

} 


Encapsulation 

Encapsulation is what really makes Flash so 
powerfuh Converting either the language or visual 
animation into a movieClip not only captures the 
animation but also encapsulates both Frame and 
Object scripts. Basically a movieClip becomes a self 
contained animated object that knows how it should 
behave to specific events. Once encapsulated as a 
movieClip multiple copies can be dropped on the stage 
and each plays independently. We have encapsulated 
and extended the code from this article to produce a 
couple of different web games. The games and source 
code can l>e found at www.hotFlashBQQk.com 

Conclusion 

While certain problems clearly require a language- 
based solution, such as score keeping in a game, a 
variety of other functions are more easily accomplished 
using the visual paradigm. To see two examples that 
appear fairly complex but were easily accomplished 
using the visual solution visit the web site listed below. 
The fact that these functions can be accomplished with 
little code and an aptitude for logical thinking makes it 
easy to see why many creatives are so excited about 
Flash. It is interesting that, when presented with a 
Flash problem, we l>oth tend to look for code-based 
solutions first, yet on several occasions we have been 
delighted to discover simpler visual solutions that met 
our needs. One thing that is clear is that ActionScript 
programmers need to be familiar with Flash and its 
visual capabilities as well as the scripting language. An 
excellent resource for both novice and experienced 
Flash users is the book EZ Flash 5 by Bradley Kaldahl. 
Tt uses short 2-8 page hands-on projects to provide a 
wealth of both visual and code-based ideas and 
solutions. To find out more about the book EZ Flash 
5 visit www.hotFlashbook.com 


on (rollOver) [ 
stop () : 

} 

on (rollout) f 

gotoAndPlay (40 - ^currentFrame + 100 ): 

1 
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PALM 

PROGRAMMING 


By Andrew S. Downs 


Web cupping 


Downloading a Palm OS Web Clipping 
Application via a Servlet 


Palm OS'* Emulator 


Introduction to web cupping 

Several years ago the Palm VII introduced users to the 
wireless web through its built-in browser CWeb Clipper, or 
simply Clipper). This browser suppons Web Clipping 
Appiications (WCAs), thin-clients built using PalnTs supported 
subset of HTML. WCAs may contain pages consisting of controis, 
text, images and links. 

A WCA is a specialized type of Palm OS database (as are 
other Palm OS apps). You construct a WCA using Palm's 
builder took Note that, although a hierarchy of directories and 
files may be used when building the WCA, inside the database 
everything exists in one logical directory (retaining the original 
file names), thus requiring unique names across a!l input files 
(both HTML and images). 

An advantage to this database-oriented approach is that all 
of the elements necessary to display a set of pages may be 
assembled into one package for download and subsequent 
browsing. A continuous network connection is not required for 
viewing die pages, although it is possible (and common) to 
place live links on those pages. 

The WCA discussed later in this article contains no live 
external links (see Figure 1). One l>enefit of this approach is 
that no additional web access is required when constructing or 
using the WCA, saving lx>th time and money. (Tlie Palm Vll 
wireless network can be slow and expensive, which becomes an 
important factor if you need to build a WCA dynamiailly or 
access live data.) The application descril>ed here functions the 
same over a wireline mcxlem, which may be more cost effective 
than a wireless connection. 


Sample WCfl 


Coiirtes}^ of the Web 
Clipping sample servlet! 



Figure 1. The WCA running under Clipper in the Palm 
emulator 


Non-Palm VII owners: Web Clipper Ls also included in the 
Mobile Internet Kit, a software upgrade diat allows other Palm 
devices to access the Internet. 


Andrew has worked with Palm OS since 1999- He wrote die Palm OS wireless client for Snippets Software. You can reach him at andrew@downs.ws. 
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Components 

There are several components to the system described in 
this article: 

• A native Palm app (a .prc) that initiates the request to 
download the WCA. This app contains information needed 
to connect to a server, including URL and username. 

• A Java servlet that returns the WCA from the server. 

• The raw material for the WCA. In this e^sample, it is a static 

text page. 

• The Palm Query Application Builder (QAB) that creates the WCA. 

This tool is freely available for download. As of diis writing the 
Macintosh version does not support execution via AppleScript 
or otherwise allow for command-line building or the inclusion 
of params. As always, check the Palm website for updates. 

Palm app 

The majority of the code presented in tliis article is for the Palm 
OS client application. Tlie core functionality is in the Connection 
class (C++). It sequences the calls to retrieve and display a WCA. 

Listing 1: Connection.cpp 


Cormfctlon 


Tiic methods contained here indude: 

Inii: drives the overalJ connection and download process. 

Connect: sets up portions of the http request, and handsoff to a library-specific 
method. 

LaunchClipper: invokes WebCiipper to display the WCA. Most of this method came 
horn Palm's website. 

InvokelNetlib: use the INetlib to connect to a remote URL and download data. 


const int kGetFlleSi^e “ 0| 
const int kCctFlle = 1: 
const ::Char * kUser ^ "sample": 
const ::Char * kUrl ^ 

"http://youedoroain:8080/servlet/WcaServlet": 
const ::Char * kDatabaseName = “Sample, pqa'*: 
const int klnBufferSlze - 1024: 
const int kDefaultMsgSize “ 1024; 

void Connection::InitC void ) ( 

//AJthough not an absolute requirement for a small WCA, if we know bow much 
// space the downloaded WCA will tike up, our code works more effidenUy if we 
// only allocate a temp buffer of the necessary size. Since the ConncctO method does 
// not currently return anything, there is code in InvokelNetLibO that saves the size. 
//That is not done in this method. 

Connect( kGetFllcSize, kUser, kUrl ): 

// Retrieve the actual WC^ from the server. 

Connect { kGetFile, kUser. ktfrl ); 

// Display the downloaded WCA without additional user intervention. 
LaunchClipper{ “file:Sample.pqa" ); 


void Connection::Connect( int op. ::Ghar * user, 
::Char ‘ url ) i 

//This siring holds the additional params in the hap request. 

::Char * but; 


// Set the opmtion code. 

::StrIToA( opStrlng, op ); 

// Create the intei^ng part of the request string, fonnatted for an http GET 
// method.Append the user and operation code params, 

::StrCat( buf* “?user-" ): 

::StrCat( buf, user ); 

::StrCat( buf» "&op”" ): 

::StrCat{ buf* opStrlng ): 

// Invoke a library'Spedfic method to comicct to the server 
// If we are not only using InetUb then wrap this in a conditional . 
InvokelNetLibC url* buf, op ): 

; :MeniPtrFree( buf ); 

1 

1 

// Most of this method came from Mm 's wetssite. 

::Err Connection:iLaunchClipper( const ::Char * orlgurl ) I 
::Err err; 

::Char * url ■ 0; 

::DmSearchStateType searchState: 

::UIntl6 cardNo; 

::LQcallD dbID; 

: :lllntl& length = :: StrLen( orlgurl ): 

// Copy the URL, since the OS will free the pammeter once Clipper quits, 
url - ( ::Char * )::MemPtrNew( length ); 

if ( !url ) 

return sysErrNoFreeRAH: 

::StrCopy{ url, ( const ::Char “ lorigurl 
: :MeiiiPtrSetOwner( url, 0 ): 

// Locate and launch Gipper 

err “ ::DmGetNextDatabaseByTypeCreator( true. 

SaeatchState, syfiFlleTApplication, syaFileCClipper, 
true, ScardNo, &dbID ); 

// If CUpper b not presem... 
if ( err ) { 

::FrmAlert{ NoCllpperAlert J: 

:iMemPtrFreef url ]; 

i 

else I 

err ^ ::SyaUIAppSwitch( cardNo, dblD, 
sysAppLaunchCmdGoToURL, url ): 

] 


return err: 

J 

long Connection:;InvokeINetLib( ::Char ^theURL, 

:;Char *tbeSuffix. int selector ) I 

long retval = -1; 

static int inBufferSize = 0: 

// Setup buffers. 

::Char * in = (::Char *)::HemPtrNew[ klnBufferSise ): 
:;Char * out “ 

( ::Char * ): :HeiiiPtrNewC kDefaultMsgSlze ]: 

//After this, we have a uri in the buffer similar to: 

// hitp://www.yourdomain:8080/WcaServJct?user=sample& op=0 
;:StrCopyC out. theURL }: 

::StrCatC out. theSuffix J: 

: ;Err err: 


//The string representation of the operation code goes here 
::Char opStringl 2 1: 

//Allocare a bufrer for our outgoing request.The de&uJt size is stored in another class, 
buf ^ ( : rChar * ) i :MnmPtrNev( kDef aultMegSlze ) ; 

if t buf ) I 
// hiitiaUze the string. 

::MeiiiSet{ buf. kDefaultMsgSize, '\0' ): 

: :MeiiiSet( opString, 2, ’\0“ ): 


:;IJIntl6 libRefnum: 

// Load net library. 

err = ::SysLibFind( "INet.lib". &libRefnura ): 

If [ err ) [ 

ErrNonFatalDisplay( “Unable to find INetLib* ); 
goto close: 
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: : MeniHandle inetH; 

::Urntl6 indexP; 

::INetConfigNameType config: 

// Other possible values incMe bietCfgNameCTFWirelcss and 
// inetCfj^ameDefWireless. 

i:StrCopyC conflg.narne* inetCfgNameCTPDefault ); 

// Gel the eonliguration index of the net library. 

err ^ ::INetLibConfiglndexFromNaDte( libRefnun^ &configt 
ficindexP ) ; 

// Open the net library. 

err = ; :INetLibOpen( libRefnum^ indexP» 0* NULL, 0* 

&inetH )i 

// Minor adjiistmenU to ihe INeilib settings. 

// Set the buffer sbse. 

long tempValue = klnSufferSlze: 

;:INetLibSettlagSetC libRefmim. InetH. 
inetSettingMaxlspSize, itempValua< 
sizeof( teinpValue ) )j 

// Disable compression, 
tenipValue “ ctpConvNone; 

:; iNetLlbSettingS et[llbRefnum * inetH. 
inetSettingConvAlgorithm. &tempValue. 
sizeof(tempValueJ): 

: :MeniHandle theSocket: 

// So we don't wait forever.,, 

::lTit32 timeout = r t SysTicksPerSeeond () * 15: 

// Send our request to the URL spediied in our output buffer, 
err ” : ;INetLibtJRLOpenf llbRefnuni. inetH, 

{ mifilgned char ‘ )out, NULL, itheSocket, timeout* 
inetOpenURLFlagForceEncOff }; 

::UInt32 bytes = 0. tempBytes = 0: 

::DlTitl6 status ” 0; 

t :INetEventType event: 

bool ready = false: 

//Wait for a change in the socket’s status, which will be the signal that there is a 
// response to ptocesis. 
while { !ready ) ( 

: :INetLibGetEvent( libRefnum, InetH, &event* timeout ): 

if ( event,eType ™ inetSockReadyEvent || 

event,eType = inetSockStatusChangeEvent ) 
ready = true: 

I 

::Int32 inHaxBufferSize = kInBnfferSize; 

if ( selector = kGetFile && InBufferSize E= -1 ) 
inMaxBufferSize - InBufferSize: 


ColendarMonster i .2 
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The best FMP colendar experience 

- Fast, fast, fast!!! 

- Platform-appropriate user experience 
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• Excellent Developer Support 
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with your FileMaker Pro projects 

- 1 00% live data, 1 007a modular, no plug-ins 

- FileMaker Pro 4 or 5 (including 5.5} 

- As little as 2 ScriptMaker calls 

- Dedicated developers' utility 


OSX Carbon 
MocOS 7.1-9.x 
Windows 95-2000 




: :UIlit32 numBytea = kDefaultMsgSize: 

//The value of in will change as data gets read into the buffer, so save the original 
// address for Uter. 

: iChar * oldin = in: 

// Read incoming data, looping while there is still data available and we have not 
// downloaded the entire WCA (when applicable.) 
do ( 

tempBytes ” 0: 

if ( ( inMaxBufferSize - bytos ) < kDefaultfIsgSize ) 1 
numBytes = inMaxBufferSize - bytes: 

J 

err = INetLibSockReadf libRefnum* theSocket, in, 
numBytes, ^tempBytes. timeout ): 

//Advance pointer 
in += tempBytes: 

// hiciement byte count, 
bytes +“ tempBytes: 
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I while ( ( tempBytes != 0 ) && 

( bytes < inMaxBufferSise ) { I err ) ); 

// Qosc socket, 

err = :: INetLibSocKloseC libHefnum^ theSocket ); 

// Restore pointer to incoming data, 
in = oldin: 

if {selector kGetEileSize && bytes > 0} I 
InBufferSize = :iStrATolCin): 
t 

if (selector = kGetFile bytes > 0) i 
//The expected WCA name shciuld be in the stream, 
iiChar * dataP = ::StrStr[ In, kDatabaseKame ); 

if ( dataP -- NULL ) [ 

ErrDisplayC "String not found" ): 
goto close: 

1 

Int32 num = bytes - { dataP ’ in ); 

::LocaiID Id = ::DmFindDatabaset 0, kDatabassName }; 
if ( id 1 = 0 ) t 

err = ::DmDeleteDatabase( 0, id }: 

if ( err 1= ertNone ] 
goto close: 

// We wilJ first write the raw data to a temporary database. 

// Check whether that database already exists (a bad thing) 
id = : :DiDFindD6taba3et 0, "tempSample" ); 

// If we did not clean up previously, delete the temp database, 
if ( id I- 0 J I 

err ” i :DinI>eleteDatabase ( 0, id ): 

if ( err 1= errHone ) 
goto close: 


// Create a temp database, assigning (Clipper as the owner, 
err * : :DmCreateDatabase( 0. "tempSaniple'', Gx63bc7072. 
0x70716120, true ): 

// Note: from here to the end of tire method some i>f the error dieeklng has been 
// relaxed in order to shorten this example. Production code should check every 
// return value and take appropriate action, 
if ( err errHone ) 

ErrDisplayl "DmCreateDstabase() returned err !“ 
ErrNone"); 

// Ensure that our eieatjon attempt succeeded. 

id = :;DiaFindDatabase{ 0, "tempSample" ); 

if ( id “ 0 ) 

Errl}lsplay( “DmFiniDatabase() returned id = 0" }: 

// Open the database for writing. 

::DmOpunRef ref “ ;jDmOpenDatabase( 0, id, 
dmModeReadWritE ): 

If Cref 0} 

ErrDisplay{ "Error opening database" ): 

// Create a resource of type ‘pqa 

: :MeiiiHandle res = ; :EinNewResourceC ref. 0x70716120. 0. 
num }: 

If ( res -= NULL ) 

ErrDisplay( "DmNevResourceO returned NULL" ): 

// Lock the resource for use, 

: iMeinPtr ptr ^ : :HeinHandleLnck( res ); 

if ( ptr = 0 } 

ErrDisplay( "HemEandleLock() returned 0" ): 

// Write the resource into the database, 

err = : :DmWrite{ ptr, 0, dataP, nuat ): 


If f err !- errKone ) 

ErrDisplay( "Error writing resource" J; 

// Ose the raw data to create the “real’’ WCA. Not condoned by Pkkn 
// for aon-5>'^stem databases. 

err = : :lhiiCreateDatabaseFroiiiIiiiage( ptr J; 

// Unlock and free up memory. 

err = : :MeniHandleOnlock( res ); 

if ( err 0 ) 

ErrDisplay C "HemHandleUnlockO returned err 1“ 0" ): 

art “ DmReleaseResource( res ); 

// At this point we arc so dose to being done that success is likely. 

// StilL for consistency we check result codes, 
if C err != errHone ] 

ErrDisplayC "DmReleaseResourceO returned 
err !” errHone" ); 

err = ::DmGloseDatabaseC ref ]: 

if [ err != errNoue ) 

ErrDisplayC "DmCloseDatabaseO returned 
err != errNone" ): 

// Remove the temporary database 

err ^ :iDmDeletsOatabaseC 0, id ): 

// Locate the real database and check that we can open it for reading, 
id = : :DiiiFindDatabase C 0, kDatabasuHame ): 

if C id 1- 0 ) f 

ref = ;:DmOpenDatabase( 0 . id, dmModeReadOnly ): 
err ^ : :DinCloseDatabase{ ref ): 

// Return the number of bytes read, 
retval = bytes: 

close: 

err = ::INetLibGlose{ libRefnum, InetH ): 

// Cleanup allocated memory, 
if t out J 

: :MeinPtrFree { out ): 

// Reset pointer. 

In ^ oldin: 

if C in 3 

: IMeniPtrFreeC in ); 

return retval: 

I 


A Starter WCA 

ITie Web Clipping Application in this example is intentionaJly 
simple. A WCA gets created using the Query Application Builder 
tool from one or more H'TML and image files. This example 
contains static text only, contained in one source HTML file. You 
can extend this WCA by adding a link or bunon that triggers a 
fetch of the latest information from the server. 


LL^ting 2; index.htmJ 


A starling pomi for a Web Clipping Application (WCA). Note the inclusion of the Rikh 
identifier in the meta tag. 

<html> 

<head> 

<meta naiiie="palEconiputingplatform" content="true"> 
<title>Saniple WCA</tltle> 

</head> 


60 


Web Cupping 


MacTech • August 2002 






I’d rather create clocks than Invoices. 

If I wanted to keep books all day, f'cf have been an accountant. 



Small Business. 


MYOB software is the simplest, most powerful, most complete 
solution for managing my company on the Mac, from the day to day 
to the bottom line. 


Smart Solutions.^'^ 


AccountEdge on the Mac. 

Softwane includes QulckBooks- converskjn 
uUfity, MYOB also oSJers convetssan service. 


JUitIque frames. Quartz movements. ThaVs my business. 

MYOB software woiks for me. 


BOO.322. M Y OB 
m y 0 b c o rc ' u s 








<bo<jy> 

<h3>CotLrtesy of the Weh Clipping sample servlet ></h3> 
</body> 


The servlet 

The Java servlet illustrated here responds to client http 
requests, and can run on sometliing as simple as Sun’s 
servletrunner application (found in older versions of the Servlet 
Development Kit.) This servlet’s primary task is to return the 
(already-built) WCA associated with a particular id. 

This servlet accepts two parameters in the http request: 

• the name of a user, allowing us to return WGAs tailored to 
specific individuals, group, etc. 

* an operation code, allowing for multiple tasks to occur. This 
servlet can return the size of the WCA as a separate operation. 
This allows a client to request the WCA size first, setup a 
buffer to hold the acaial WCA, then request the WCA itself. 

Listing 3: WcaServleCjava 


WdScfvIct.jm 

Becdvc http requests from clients and return a built WCA, 

import java.io.*; 
import java,net,*: 

import javax.eervlet.*: 
import javax.servlet.http.* I 

public class WcnServlet extends HttpServlet ( 

// Elements passed in the request string, 
static final String kOperation ^ “op"t 
static final String kUser ” “user"*: 

// Operations we handle. Passed in request string, 
static final int kGetFlleSize ” 0: 
static final im kGetFlle = 1: 

// Name of actual pqa file should tx* the same for all users. For flexibility, we can 

// retrieve it ftoni different folders as needed. 

final String kPqaFllename = “Sample.pqa*: 

// Name of base directary {relative to servlet dir) fitim which to build path to pqa. 
final String kPartialPath = “dev/pqa/“: 

// Most servlets do most of their work starting fitjm doGetO or doPostO 
public void doGet{ HttpServletRequest request, 
HttpServletResponse reaponae ) 
throws ServletExceptian, lOException I 
// We can handle different uscrs.The request carries the username as a param. 
String user ^ requeat.getParameter{ ktJser ); 

// The operation of interest alst> gets passed as a param. 
int op = Integer.parselnt( 

( String Jrequest.getPflrametert kOperation ) ): 

//ITie output stream is where our response will go. 

ServletOutputStream out = responae.getOutputStrGamOj 

switch { op ) [ 

//The tile size Is important when the receiver needs to know how big a buffer 
// to allocate for incoming data, 
case kGetFileSize: 

File pqa = new File( kPartialFath + username 
+ + kPqaFilename): 

//Write the file size to the output stream. 

if ( pqa !“ null && pqa.exists{) && pqa.isFile()) 
out.println( pqa*length{) ): 

break; 

// Return the actual pqa in the output stream, 
case kGetFile: 

// Build the path to the file, and attempt to open the file. 


FllelnputStream fis = new FlleInputStreaiii{ 
kPartlalPath + user + + kPqaFilename ); 

if ( fis null ) [ 

// Open a ^pjpe“ to get data out of the file. 

DatalnputStream bis “ new DataInputStreamf fis ); 

// Copy the pqa to the output stream.This particular implcmematton can 
// be impmved upon by copying more than a byte at a time, 
while ( bis.available() > 0 ) 
out.write( bls,readByte{) }; 

bis.close(); 
fis.closei); 

out.close[); 

1 

break; 

default: 

break; 

1 

I 

It is possible to extend this servlet to dynamically build a 
WCA on demand. This would allow up-to-the-minute data to be 
inserted into a WCA targeted at a particular user. The operation 
code allows for some sophisticated handling of such user 
requests. For example, the servlet could respond to an initial 
request for a WCA by .spawning a thread to build that WCA 
dynamically. Since it takes time to perform such a build, 
particularly if data must be fetched from the Internet, it would 
be desirable to add some status codes to the process, A client 
can request the current status of the build, locip while it is not 
complete, then request the WCA itself. 

Enhanqng the system 

There are many bells and whistles that can be 
incorporated into this system. For example, the Java servlet 
may connect to an LDAP server to validate the user and 
obtain user-specific configuration information. Several servlet 
engines are available that can run this servlet, including the 
servletrunner application from Sun (good for testing), and 
apache,org’s Tomcat. Non-Palm OS devices may be supported 
by the servlet; the type of client requesting a file could be 
sent as a param in the hup request. 

Many WCAs consist of one or more statically coded 
pages. But dynamic pages often work much better if you have 
access to a reliable mechanism for generating those pages. 
Java servlets provide an easy way to gather pages, build a 
WCA via a command-line prompt, and then download the 
WCA to the Palm device. 

An alternative to building the WCA using the Palm tools 
would be to write the database format directly. Although the 
formal has probably remained static over the past two years, it 
requires time (and money) to implement such a writing 
mechanism, whereas the build tools can be downloaded and 
setup very quickly. 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Westford, MA 


Endgame 

The Chess players among you have another opportunity to 
excel this month. Back in 1995 (have I really been writing this 
column for that long?), we had a Challenge that required readers 
to identify all possible chess positions from a given board 
position. Gary Beith woo that Challenge, and you might want to 
refer back to his solution when thinking about this month's 
problem, which invites you to solve the chess end game. 

This month’s problem is formulated as a C++ class. The 
prototype for the code you should write is- 

typedef ^n\m ( 

kEmpty=0, kPawn. kKnlght* kEishop, kRook, kQiieen, kKing 
I ChessPlecer 

typedef enum { 

kNone^, kWhite^^l. kBlatk 
J Player: 

typedef struct SquarE [ 

ChessPiece piece; 

Player player: 

} Square: 

typedef struct PieceLocatiQn 1 
char row: 
char col: 

) PieceLocation: 

typedef Square Board[8][8]; 

/■ indexed as [now] [col] 7 
r white start row is 0 V 

/* columns numbered Jeft to right viewed from row 0 7 

typedef struct Move I 
Board board: 

/* board before move is made 7 
Player playerMoving: 

/* whiti player is making this move 7 
PieceLocation pieceBeltigMovcd; 

r which piece is being moved 7 
PieceLocation destination; 

J* where is pieceBeingMoved being moved to 7 
Move *alternativeMove; 

/* list pointer for alternative moves by playerMoving; 

MM if no more alternatives */ 

HoV e * s ub s equentMove: 

/* subsequent move in this move tree, made by opponent to pJayerMoving, 

MILL if no subsequent move is possibJe 7 
bool movelsCapture; 

r true if this move is a capture 7 
bool moveIsCheck; 

r true if this move places the opponent in check (but not male) 7 
bool movelsMate: 

/* true if this move mates the opponent 7 
bool move1aP r omo tion: 

/* true if this move promotes a pawn at the 8th tank V 
ChessPiece pieceAfterPromotion: 

/* valid only if movdsPromotion is true, set to value of new piece 7 
I Move: 

class EndGame f 
Board board: 

Move. *lnitialMove: 

/* add other private members as you see fit 7 
—EndGaEie (void) { 

r your destruaor code goes here 7 


public: 

EndGame(Board initialBoard. Player playcrToMove) I 
your constructor code goes here 7 

) 

Move *Solve{) { 
r your code goes hea^ */ 
return movcTtee: 

I 

I; 

The construaor for your EndGame class is provided with the 
initial board configuration (board) and the identity of the player 
who moves first (playerToMove). When your Solve method is 
called, your job is to choose an initial move that leads to checkmate 
in the minimum number of moves possible. You also need to 
compute the possible opposing moves with which the other player 
might respond, and your response to each of thexse moves, and so 
on, until each branch of the tree results in checkmate. 

Either your construaor or the Solve routine should allocate 
storage for your first move (moveTree). The Move structure 
contains the board configuration prior to making the move, the 
identity of the player making the move, the location and 
destination of the piece being moved, and some boolean values 
indicating the results of the move. It also contains a pointer to 
the next ply of the move tree (subsequentMove), and a pointer 
to alternative moves in the current ply (alternativeMove). The 
former contains moves made by die opposing player in response 
to this move, while the latter contains other moves that could be 
made by the current player instead of this move. Together, they 
allow you to describe tJie entire move tree. 

Your destructor needs to free any memory allocated for the 
Move data structure. 

In calculating moves, you can assume that any casding that 
might take place has already done so. You can also ignore the 
possibility of en passant pawn moves. You do need to consider 
the possibility of promoting a pawn by moving it to the 8*^ rank 
of the board. The Move data structure makes provision for 
specifying the type of the promoted piece. 

The winner of this Challenge will be the entry that correctly 
solves all test case.s in the lea.st amount of execution time. 
Correctness means identifying all moves in the move tree, and 
guaranteeing checkmate in the minimum number of moves. 
Timing will include the con-structor, a call to your solve routine, 
and a call to your destructor for a sequence of boards. 1 am 
eliminating the subjeaive evaluation factor for this Challenge 
because of questions about fairness, but both readers and I 
appreciate code that is clear and well commented. 

This will be a native PowerPC Carbon C++ Challenge, using 
the Metrowerks Code Warrior Pro 7.0 development environment. 
Please be certain that your code is carbonized, as I may evaluate 
this Challenge using Mac OS X. 
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Winner of the May, 2002 Challenge 

The May Challenge asked users to assemble a Jigsaw 
puzzle, 'rhe puzzle was presented as a color bitmap, with each 
piece of the puzzle consisting of contiguous pixels of a unique 
color The pieces were disassembled and rotated by some 
multiple of 90 degrees. All of them were 'Tace up”. The puzzle 
was guaranteed to be rectangular in shape, and the pieces were 
guaranteed to fit together in only one way. The top left corner 
of the puzzle was in the correct position, wliich removed any 
ambiguity about orientation. Congratulations to Tom Saxton for 
submitting die winning entry for this Challenge. 

Generating test data for the Challenge is often, well, a 
challenge, and this was particularly the case this month. I 
needed to ensure tliat tlie puzzle pieces I generated fit together 
witliOLit ambiguity. And while I could have generated puzzle 
pieces using “cuts” based on straight line segtiients, I wanted 
pieces dial resembled real jigsaw puzzles. After struggling with 
this for some time, 1 nearly despaired of diis objective, but 
eventually I found something that seems qtiite pleasing. 

The first step in puzzle generation was to divide the puzzle 
into a roughly rectangular grid. For this, I decided to 
superimpose several cosine waves with random amplitudes, 
wavelengths, and offsets. 1 settled on summing four cosine 
functions for each horizontal or vertical ^'cut” in the puzzle, with 
amplitudes Ixjtween 5% and 10% of the average piece .size and 
wavelengths between 33% and ^30TO of the average piece size. 
1 repeatedly divided the puzzle into different colors for each of 
these horizontal and vertical cuts. This created a rectangular grid 
of uniquely shaped pieces with pleasantly curved edges, 

I could liave stopped there, but 1 reaily wanted to have pieces 
tliat had tlie protuberances or ""ears" commonly found in real jigsaw 
puzzles. Being uncertain about how to create these using 
mailiematics, I tiioughi about creating ears manually and "stamping” 
tliem onto each edge, modiiying tliem sligiitly to make tliem unique, 
Tliat idea lasted all of about fifteen minutes, as tedium drove this 
tliougiti from my mind. Eventually, I decided to experiment with 
line of my favorite programs, Grapliing Calculator. An early version 
of GC came bundled witli M^icOS for some Lime, but <plug> tlie 
commercial version http://WWW.pacifict.com offers significantly more 
functionality </plug>. Anyway, GC has helped me out in tlie past, 
so I started experimenting, and ran across tills sample equation: 

■ (x^ 4- + sin4x + sin4v) < ] 



Looking at the part of this equation tliat is above the x axis 
with -l<x<0.5, it seemed pretty close to what I was looking for. 
And randomly varying tlie amplitude of the sin functions caused 
the ear to take different shapes. Tlie coefficients in tlie sin fimctions 
needed to be constrained to between about 1.5 and 5.5 in order to 
prevent the ear from being pinched off and disconnected from the 
base. In my first few puzzles, a few of these discooneaed pieces 
bypassed detection by me, but not by contestants, so I eventually 
settled on a more restricted range of parameters that generated 
slightly less inieresting, but still acceptable, ear shapes. For each 
edge, I .selected a legation somewliere in tlie middle of the piece, 
randomized the direction of tlie ear (with a small probability of 
having no ear at all), superimpased the x axis atx)ve onto the 
curved line described above, and adjusted the piec'c lioundary 
according to the portion of a shape like the one above located 
above the x-axis (or, for vertical lines, tlie portion right of the y- 
axis, Tliis aimed out to be less trivial than 1 liad hoped, especially 
lieing careful to avoid aeating those pesky disconnected pieces. 
Preventing one ear fiom intersecting with another ear and cutting 
a piece in two proved to be an additional complication, hut the 
end result looked like this: 



Tom locates the individual pieces of the puzzle in his 
_FFindPieces routine, and creates four bitmaps per piece, one 
for each possible rotation, in _FBuildPceBitmap. He detects edge 
pieces in the _GetEdgelnfo routine, marking them as such for 
future use. Aiter placing the upper left piece in its guaranteed- 
correct position, the heav^^ lifting is done by the _FSolvePce 
routine, which solves the puzzle from top to bottom, left to right. 
Tom cliecks each possible rotation of each piece against the 
current piece location using two passes, the first trying to look 
at only pieces with tiie correct "innie/outie” (Tom's term) match, 
and the second to pick up pieces to weirdly shaped to be missed 
in the first pass. The logic Ibr matching two pieces is rather 
intricate, and can be found in the _FTestPce routine. 

Ernst solves the puzzles by first creating a vector array for 
each piece that described a clockwise path around the piece. He 
assembles the pieces by inserting them into a Shell data 
structure, first placing the edge pieces, and spiralling inward 


66 


MacTech • August 2002 










toward the center. While his solution is very Fast, it became 
confused on the largest of my test cases* a problem tliat Ernst 
attributed to a lack of backtracking logic, 

I evaluated the entries using 6 test cases that ranged in size 
from 24 pieces to 3750 pieces. Both Ernst and Tom were 
credited for including an optional feature to display the solved 
puzzle. Tom also displayed the puzzle in its disassembled state, 
and included options to display PICT and Jigsaw files, for which 
he earned a feature point reduction bonus. Ernst earned a larger 
point reduction for code clarity and commentary. 

The table Ix^low lists, for each of the solutions submitted, tlie 
total execution time in seconds, the bonuses for clarity and for 
displaying the solved puzzle, and the total score. It also lists the 
programming language used for each entry. As usual, the number 
in parentheses after the entrant's name is die total number of 
Challenge points earned in all Challenges prior to this one. 



Time 

(sees) 

Cases 

Correct 

Clarity 

Bonus 

Features 

Bontis 

Score Language 

Tom Saxton (ZIO) 

597.1 

6 

O.JC 

0,25 

mi C++ 

Ernst Mumer f872) 

89.9 

5 

0.25 

0.20 

49,5 C++ 


Top CoNTESTAim ... 

Listed here are the Top Contestants for the Programmer's 
Challenge, including everyone who has accumulated 20 or more 
points during the past two years. Tlie numl>ers below include 
points awarded over the 24 most recent contests, including 
points earned by this montli's entrants. 


Rank 

Name 

Points 

Wins 

Total 


(24 mo) 

(24 mo) 

Points 


T 

Munter, Ernst 

243 

8 

872 

2. 

Saxton, Tom 

65 

2 

230 

3. 

Taylor* Jonathan 

57 

2 

83 

4. 

Stenger, Allen 

53 

1 

118 

5. 

Rieken, Willeke 

42 

2 

134 

6. 

Wihlborg, Claes 

40 

2 

49 

8, 

Gregg* Xan 

20 

1 

140 

9. 

Mailett, Jeff 

20 

1 

114 

10. 

Cooper, Tony 

20 

1 

20 

IL 

Truskier, Peter 

20 

1 

20 


Here is Tom's winning jigsaw solution* The code had been 
abridged for publication because of page constraints; see 
http://www,mactech,com for tlie full version. 

JiGSAW.CP 

Copyright © 2002 
Tom Saxton 

r 

* Jigsaw 

¥ 

* Created by Tom Saxton on Thu Apr JS 2002. 
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• 15 Fully Integrated Tools- 
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NameCleaner 

An industrial-strength utilit/ to manipulate file names 
and types, focused on preparing Macintosh files 
for use under Windows and Unix, and vice versa. 
Available with previewing, logging, scheduling 
and scripting - download a trial version from our 
website for OS 7/8/9 or OS X. 

www.sig5oftware.com 
Email: sales@$igsoftware.com 



Keep track of every second of your time and bill 
for it with Time TrackI Built in instructions make 
it easy to use. it is o simple way to manage your 
billable time for multiple projects and create a 
web page to show to your clients. Only $24.95 
per single user license per platform. Finally! A 
versatile time tracking solution for Macintosh, 
Windows, and Palm! 


www.tr i nf i n itysof twa re.com 


InformlNIT 

The ultimate guide to the Classic Mac OS 
& the Classic Environment in Mac OS X 

5 Mice/SCars-Macworfd 
Authoritative, a Must Have-MacAddfct 
Shareware of the Year-MacUser 
The ultimate troubleshooting guide-Mac Toiby 
The ultimate primer-ZDNet 

wwwJnformlNIT.com 


Eudora Internet Moil Server (EIMS) 
3.1 is the btest version of the most 
popular Internet mai! server for the 
Macintosh. If you need to handle 
email for o dozen users^ or 
thousands of users, EIMS is a 
reliable and easy to use solution. 

EIMS 3J is ovflilable for USS400.00, tkre ore no limits on the number of users 
that con be added, and free email support is included. 

for more information, see 

http;//www.euclora*co.nz/ 


GraphicConverter converts 
pictures to different 
formats. Also if contains 
many useful features for 
picture manipulation. 

See wwwJemkesoftxam 

for more information. 
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By TLA Systems 
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numerous coloring modes. This is an effect that you see 
everyday on TV and in many movie titles. Shine is available 
for Moc, Mac OSX and Windows. 


WWW. trapcode.com 


TIv/oKfW tf Mofmtifih lednfokis? Jk /Jrw&yjjwJfT 



Got o great product sold through Kogi? 

Promote your product through the very cost 
effective Kogi Showcase in MacTech Magazine. 

For more information, contact us at 

adsales@mactech.com 


August 2002 • MacTech 


69 
















^include <Carbon/Cai:bon*h> 

#1n c1ud e "jig s aw.h" 

// make sure we aren't using printf in die nouHConsoJe builds 
#lfndef UI_CONSOLE 
?Mefine priutf error 
tfendif 

typed ef struct PT PT; //a point 
struct PT 
[ 

int 5c, y: 

1 : 

#define aNil Dx7FF¥ 

typedef struct EDGE EDGE: //inlb about an edge 
struct EDGE 
1 

char fEdge; 

typedef enum 
I 

btMask, 
btEdge 
1 BT; 

typedef struct ROT ROT: 

St rue t HOT // info for a notation of a piece 
{ 

Int tnruReject: 

EDGE aedge[4]: 

BitHap bitiDapKask; 

BltMap bitmapEdge; 

] : 

typedef struct PGE PCE; 

struct PCE // a single piece, including its four rotations 

t 

long cpixel; 
ushort clrr 
cbac cEdgeSlde: 
char irotUsed: 

ROT arotl4]; 

I: 

typedef struct PUZ PUZ: 
struct PUZ // the puzzle solving state 
( 

// challenge state maintained by host 
CS *pcs: 

// the image data, (fifst the input fde, then the output file after extracting the pieces) 

BITS bits; 

int fChangedSize: 

// bitmap mask for the puzzle as we decompose then solve it 
BitMap bitmapHask; 

// the array of pieces 
int epee; 

PCE *papce: 

// memory block from which we allocate the bitmaps of the individuaJ pieces 
char *pabBuffer: 
long cbBufferAlloc; 
long cbBuff erUsed: 

if the current Rdution state 
int ipceHext; 

Rect reetPrev: 

int xRightEdge* yBottomEdge; 

int cpceRcw; 

int yTopUnsclved; 

long cpixellmage: 

long cpixeiPuzzle: 

long cpixelSolved: 

AbsoluteTime ticksTotal: 

AbsoluteTinte tickStart; 

h 


// define adjacency 
typedef struct DIR DIR: 

struct DIR //a direction to move to an adjacent pixel 
1 

int dx» dy: 

}; 

// directions to look when checking the left edge of a piece 
static const DIR s_adlrLeft[] - 
{ 


0 . 

1 

- 1 . 

1 

- 1 . 

0 

- 1 . 

-1 

0 . 

-1 


]: 

// directions to look when checking the top edge of a piece 
static const DIR s_adlrAbove [] - 
[ 


1. 

0 s. 

1- 

‘1 1- 

0. 

1 1. 

-1. 

-1 L 

-1. 

0 }. 


1: 

onuEi 

{ 

iodgeTop = 0. 
ledgeLeft, 
iedgeBottom, 
iedgERight. 
eedge 


U directions to look when finding the boundary of a piece 
static const DIR s_adirEdge[cadge] = 

[ 

11 - 01 , 

I 0, 1 ). 

f -1. 0 ]. 

I 0. -1 }. 

1 : 

// funaion prototypes deleted for brevity 


Sohvjlgsaw 

// the public entry point to the puz/Je solver 

void SoiveJigEaw[CS *pcs, const char psaFilell) 

1 

long cbRead; 

OBStatus ec: 

int cSolved = 0: 

FH fnOut = fnNll; 

double musecTotal = 0.0: 

// init the puzzle structure 
PlIZ puz: 

oiemset C&puz, 0, sizeof (PDZ)) ; 
puz,pcs = pcs: 

// open and read the challenge file (omitted for brevity) 

// errate and open the output fde (omitted for brevity) 

// process the cases 

for (: iCase cCaae: ++iCase} 

( 

// note the starting time 

puK.ticksTotal = s_tickZero: 

puz . tickStart = UpTitnaO; 

#lfdef UI_C0NSOLE 

printf ("process case X-d of %d:\n", iCase, cCase): 

#endif 

// load in the image 

if (I_FLQadData(ipuzI ICase)) 
break: 
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#ifdef Ul_GtJI 

// put the stalling image into the output window 

puz.ticksTotal = AddAbsoluteToAhsoluteCpuz-ticksTotai, 
SubAb 3 o]-uteFroinAbsolut&(UpTinie()» puz. tickStart)): 
DrawBits (puz. pcfi. puz^bits. puz .JtRightEdge» 
puz^yBottomEdge]: 

puz.tlckStart = TJpTlmeC); 

#endif 

// let‘s find ali of the pieces 
if Cl_FFlndPlEceE{&puz)) 

1 

_FreePus{&puKS: 
continue: 

1 

// place the first piece into the output buffer 
_PlacePce (Sipuz. 0, 0, 0, 0): 
tfifdef UI_GUI 

puz.ticksTotal = AddAbEoluteToAbaolute(puz.tlcksTotalt 

SubAbEolnteFromAbsoluteCDpTinieO , puz .tickStart)): 
DrawBits(puz*pcs* puz.bits* puz*xRightEdge. 
pnz*yBottainEdge); 

puz.tickStatt = tfpTimeO: 

#endif 

while (puz.IpceKext < puz.cpce fiiSt _FSolvePce(£(puz)) 

I 

#ifdef UI,G0I 

puz,ticksTotal = AddAbsolutaToAbsoluta(puz^tickaTotal* 
SubAbsolutcFromAbsolutetUpTinteO , puz .tickStart)): 
if [puz.fChangedSize) 

( 

BrawBita{puz.pcs. puz.bits* puz^xRightEdge* 
puz.yBottomEdge): 
puz.fChaugedSize “ fFalse: 

) 

else 

[ 

UpdateBits(puz.ptis* puz*bit£* puz.rectPrev); 
puz .tickStart = UpTimeO: 

//end if 

1 

// if we coiuplctely solved the puzzle, write out the solution 
If (ptiz .IpceNext = puz.cpce) 

{ 

tfifdef UI^CONSOLE 

printf(”\tpuzzle %d solved\u”, iCase): 

//end if 

// write out our solution 
if [ l_FWriteResult (&ptiz, iCaae}) 
break: 

-H-cSolved; 

t 

if (puz.IpceMext < puz.cpee) 

( 

//ifdef [JI_C0NS0LE 

printf('^ERRORi Solve failed after %d pieces\n”* 
uz.lpceNext): 
endif 
] 

// free the memory' used by this puzzle 
_FreePuz(&puz): 

// get the ending time and subtract the starting time to get elapsed time 
// write the time, in microseconds* to the file 
// (omitted for brevity) 

] 

#ifdef UI_C0NSOI.E 

prlntfC'Sd of Sd puzzles salved, total time = 14g\n’, 

cSolved* cCasa* musacTotal): 

//endif 

LRetJ 

_FreePuz (iipuz) ; // harmless if the puz was freed through norma] process 
if (fnCmt != 0) 


GloseFn(fttOut) * 

J 

// load in the data for a puzzk (omitted for brevity) 
static Int _FLoadData(PUB *ppuz* int iCase) 
// (omitted for brevity) 


_FFindPieces 

// locate the pieces in the input file, buMd bitmaps for them 
static int _FFiudPleceE{PUZ ‘ppuz) 

t 

int fSuccess ^ fFalse: 
ppuz->cpixel?uzzle ” 0: 
ppuz->yToptJuEolved = 0: 

uehort *psv; 

( 

const usbort *pswLiii] ^ 

&ppuz->bits,pasw[ppuz'>bitE.dx * ppuz'>bits.dy]: 
for (psw = ppuz->blta.pasw: psw < psvLim: ++p3w} 
if (*psw > ppuz->cpce) 
ppuz->cpce “ *psw: 

I 

// allocate and init the piece array 
ppuz'^papee “ new PCE[ppuz’>cpce] ; 
if (ppuz->papce — NULL) 

I 

//ifdef UI^CONSOLE 

printf("ERROR: oom allocating piece array with %d. 
enttlEs\n". 

ppuz‘>cpee): 

//endif 

goto LExit; 

1 

niemset(ppuz->papce. 0* sizeof(PCE)‘ppuz-)cpce) r 

psw = ppuz->bits.pasw; 

for (int y “ 0; y < ppuz'>bits.dy: -H-y) 

I 

for (int X = 0; x < ppuz->bitJS.dx; ) 

( 

int xStart “ x++; 
usbort clr = *psw-H-: 
if (clr -- 0) 
continue: 

while (x < ppuz’>bits.dx && *psw — clr) 

++K * sw; 

PCE ‘ppce = &ppiiz-)papce [clr-1] ; 

If (ppce->clr =0) 

t 

ppce')clr " clr: 

_SetRect(&ppce->arot[0].bitmapHaak.hounds * xStart* 
y* X. y+1): 

] 

else 

( 

_ExpandRectC&ppce->arot [O],bitniapMask.bounds. 
y* xStart* x): 

1 

} 

I 

// figure out an upper bound on how much bitmap data well need 
[ 

Int dzHost = 0: 

for (int ipce “ 0; ipce < ppuz->cpce: -H-fpee) 

I 

Rect *prect = &ppuz- 
>papce[ipcel*arot[0].bitmapMask.bounds: 

int dx = prect'^)tight - prect-)left; 
if (dx > dzMost) 
dzMost = dx: 

int dy = ptect->bottom - prect->top; 
if (dy > dzHost) 
dzMost - dy: 

I 

long cbBitntapMost = dzMost * ((dzHost + 15) >> 4) << 1: 
ppuz-)cbBufferAlloc = cbBltmapMost * ppuz-)cpce * 6; 
ppuz-)pabBuffer ” new char [ppuz-)cbBufferAlloc]: 

1 


72 


MacTech • August 2002 






for (int Ipce 0: ipce < pptiz->cpce: ++ipcel 
{ 

if {!_FBuildPceBitmaps(ppuz* ipce)] 
goto LBxit; 
tfifdef UI_GUI 

ppu 2 ->tlcksTotal = AddAbsoiuteTciAbsolute(ppu 2 - 
>ticksTotal, 

SubAbsolutePtomAbsaLuts (UpTimet) * ppuzOtlckStart) j; 
UpdateBits[ppuz->pcs. ppu 2 ->bits, ppuz- 
>papce [ipce] *arot [0] .bitiuapMasktbounds) i 
ppUK->tickStart “ UpTimeO : 
tfendlf 
I 

fSucCGss “ fTrue; 

#ifdef UI.CONSOLE 

printf("Vtfound %d pieces comprising %ld pljtels\n", ppuz- 
>cpce. ppuz'^cpixelPuzzle): 

#endif 

LExlt: 

return fSticcess: 


Turbocharge 
development 
with ^ 


_FBiiildPceBitmap 

// buiiil the required bittnaps for a puzzle piece in aU four rotations 
static int ^FBuildPceBitmapsCPUZ *ppuZt int ipce) 

I 

int fSuccess = fFalse; 

PCE *ppce = &ppu7->papce[ipce]: 

Rect rectBounde = ppce->arot[0].bitmapMask.hounds: 

if (l_FCreateBitmap(ppTiz. &ppce->arot[0].bitmapMaskp 

rectBounds.left„ rsctBounds.top. rectBounds.right» 
rectBounds*bottom)) 
goto LExitj 

if (l_ECreateBitii]ap Cppuz. &ppce->arot [0] ^hitmapEdge, 

rectBounds.left. rectBounds.top, rectBounds.right, 
rectBound s.bottom)) 
goto LExit; 

ppuK-^cpixelPutzle += ppce->cpixel - _ColorFill(Sppuz- 
>bits, 

rsctBounds. ppCG->clr, &ppce->arot[0].bitmapMask): 

_BuildEdgeBltmap{ppce-)arot[0].bitmapMask, 

&ppce * >a rot 10],bitmapEdge)j 

_GetEdgeInfo(ppuz, ppce)i 

for (int Irot “ 1: irot < DIM{ppce-)arot): ■H-irot) 

if (!_FRotateBitiiiap(ppuzH ppce->arot [0] ^hlttnapEdge ^ irot* 
&ppce->arot [irot] .bitiiiapEdge)) 
goto LExit: 

fSuccess = fTrue: 

LExit: 

return fTrue: 

] 


_FSolvePcc 

// solve for one piece of the puzzle 
static int _FSolvePcE(PUZ ‘'ppuz} 

f 

// find the first unplaced pixel 
int xTarget. yTarget: 

// start X out just to the right of the most rcccn: piece we placed, 

// unless tliat piece liit tire right edge of the puzzle 
xTarget ppuz->rectPrev.right: 
if [xTarget — ppuz->xRigbtEdge) 
xTarget “ 0: 
else 

-H-xTarget: 

// starting at the top of the unsolved area of the puzzle, march down 
// the chosen s column until we find an unset pixel 
for (yTarget = ppuz->yTopUnEolved: yTarget < ppuz- 
>yBottomEdge: 


RADicode is a RAD tool that converts 
REALbasic project files into functional 
PowerPlant GUIs using PowerPlant best 
coding practices and conventions. Get 
your application from drawing board to 
w’orking code faster than ever before. 
Compile and run die generated project, 
and go home early. 



Introductory Price 


solidvsfflg]^ 

(< 517 ) ■ 776-8155 

^^v\v. soliclwave .com 
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++yTarget) 

if (l_FGetElt(ppuz->blttnapHask* xTargett yTarget)) 
break: 

// now^ try to movt as far up md to the Jeft as possible since 
// wc'il really like to have the upper left comer pixel of the next 
// piece as our target 
while (fTrue) 
f 

if UTarget > 0 && I_FGetBit [ppuZ'HltmapMask* xTarget' 

1 . 

yTargetJ) 

'‘xTarget; 

else if (yTarget > 0 UGetBit(ppuz->bitinapMask, 
xTarget♦ 

yTarget-l)) 

'^yTatget; 

elee 

break; 

1 


// if we're Iwjking for an edge piece, consider only edge pieces 
if {yTarget = 0 | | xTarget = 0) 

{ 

if (ppce->cEdgeSide = 0) 
continue: 

if (yTatget ^ 0 &Sf !prot->aedge[iedgsTop] .fEdge) 
continue: 

if fxTarget == 0 && ] prot->aedge [iedgeLeft] * fEdge) 
continue: 


if (pass = 2 pcot->iiiruReject 1= ppuz'>ipceNext) 

I 

// some pieces are too wierd to work with the mnie/ouUc testing 

(below), 

// Jet ail the conftgunitions that got rejected previously' nm through 

// this time, but don’t test any piece twice f 

continue: 


// finally, make s^ure the target point in the leftmost unset pixel in yTarget's row 
// so diat we only have to check the leftmost set pixel of each scan line in each 
// candidate piece 

for (int xT = xTarget - 1; xT ppuz->rectPrev,left: -- 
xT) 

I 

If [ !_EGetBit (ppuz->bitniapMask. xT. yTarget)) 
xTarget = xT: 

1 

FT aptCheckf4]; 
int cptCheck = 0: 

if [ppuz->rectPrev*right ( ppu2’>xRightEdge) 

i 

PCE *ppcePrev = &ppuz->papce[ppuz->ipceNext-1]: 

ROT *prot = ^ppeePrev*>arDt[ppcePrev-)irotUsed]; 

Int cptln = _CptGetEdgEShape(prot->bitiiepHask, aptCheck): 
for (int Ipt = 0: ipt < cptln: i+ipt) 

( 

FT pt = aptCheck[ipt] ; 

_0ffEetPt Upt. 

ppuz->rectPrev.left ■ protObitmapEdgeabounds,left, 
ppuz-^reetPrev,top ‘ prot’)bltmapEdge.bounds.top 
); 

pt»X += 1; 

if t_FPtIiiRect (ppuz->bItraapMask,bounds . pt.x* pt*y) 
!_FGetBit(ppnz '>bitiiiapMaskI pt^x, pt.y)) 

aptCheck [cptCheck-H-] - pt; 

I 

J 

if (ppuz-^yTopUnsolved 0} 

[ 

const PCE 'ppceAfaove - 

fippuz-)papce [ppuz'^ipceNext - ppuz->cpceRow]; 
const ROT *protAbove = £jppceAbove->arot [ppeeAbove- 
^irotUsad] ; 

PT ptTop; 

ptTop,x = (prQtAbove->bltniapHaskabounds-left + 
prot Above - >bitTDapMask - bounds , right) / 2: 
for [ptTop.y = ppuz->yTopUnEolved: 

ptTop.y ( ppuz-)yBottoraEdge: -H-pcTop-y) 

I 

if {l_FGetBit(ppuz-)bitmapMask, ptTop-X- ptTop.y)) 

I 

aptCheck [cptCheckrH-] — ptTop; 
break; 


Rect bounds prot'>hitiimpEdge-bounds; 
for (int y “ WMin(bounds.bottom-1. 

bounds.top i {yTarget ' ppuz’>yTopUn3olved)); 
y >= bounds-top: *-y) 

[ 

for (int X = bounds.left: x < bounds.right: ++x) 

[ 

if ([_FGetBlt (prot'>bitEiapEdga * x. y)} 
continue: 

int dx ^ xTarget ’ x: 
int dy “ yTatget - y: 

// make sure ihe proposed Ixninding box fits inside the puzzle 
if (bounds.left + dx < 0 

' bounds.right + dx > ppuz->xRlghtEdge 
bounds.top + dy < D 

bounds.bottom + dy > ppuz->yBottojiiSdgE) 

I 

continue: 

] 

if (pass “ 1) 

I 

// make sure we have edge bits to joLu with check points on the 
// previous piece 
int ipt: 

for [ipt - 0 ; ipt < cptCheck: ++ipt) 
if (l_FGetBitSafe(prot->bitmapEdge, 

aptCheck[ipt] .X - dx. aptCheck[ipt].y - 


If (ipt < cptCheck) 

1 

prot->]iiruReject = ppuz->ipceNext: 
break; 

I 

[ 

if (_FTeatPce{ppuz. Ipce. irot. dx. dy)} 
\ 

_PlacePce(ppuz. ipca. irot,. dx* dy): 
return fTrue: 

] 

break: 

I 

I 


1 

] 

for (int pass = 1: pass <” 2: -H-pass) 

1 

for (int irot = 0; irot < IlIM(ppuz->papce[{)] .arot); 
++irot} 

I 

for (int ipce = ppuz->ipceNext; ipce < ppuz->cpce: 

++lpce} 

( 

PCF ‘ppce = &ppuz->papce[lpce] ; 

ROT ‘prot = &ppce->arot[irot]; 


I 

] 

return fFalse: 

1 


_FrestPce 

// test whether or not the indicated piece fits into the puzzle at 

// the specified offset from it starting position, 

static int _FTeatPce(PllZ *ppuz, int ipce. int irot. 


int fPassed = fFalse: 
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// dieck Lhai no edge pixel invades the compJetttI portion of the puzzle 
PCE *ppce ^ ippuz->papee[ipcel : 

ROT 'prot = &ppce->arot[irot] I 

BitMap *pMtiiiapEdge - 6fpi:ot->bl1:mapBdgeT 

Kect bound B ^ pbittiiapEdga->bomi[3B: 

for (Int y = bounds.top; y < bounds.bottom; ++y) 

i 

uchac mask: 

Int X = bounds.left; 

uehar *pb ■ _PbMaskPorB±tmapB±t(pbltmapEdge, x, y, 
^mask); 

for ( 1 X < bounds.right; ) 

I 

char b 
if (b — 0) 

I 

X 8; 
continue: 

I 

for ( : tnask !“ 0; ++x. mask >>“ 1) 

[ 

if {b & mask) 

[ 

If (E_FPtItiReet(ppuz’>bitinapKaak.bounds, x+dx. 

y+dy) 11 

_FGetBit(ppux->bitroapHaskH x+dx. y+dy)) 

f 

goto LRet: 


( 

if (l_FRotateBltmap(ppuz. ppce->arot[D].bltinapMask. irot. 
pbltmaprtask)) 

( 

#ifdef UI_CONSOLE 

printf(“ERROR: oom building rotated mask bitmap for 
piece %d\n''. ppuz->ipceNext): 
ffendif 

goto LRet: 

I 

J 


// now scan left edge pixels looking lor pixels dial are inierior to the proposed 
// assembled pieces in order to pass, there have to be interior edge pbtels from tlie 
// top of the piece down "most" ihe piece, with no gaps. 

I 

Int xKid = {bounds.left + bounds.right)/2: 
int yInteriorLim = bounds.top: 

int ylnterlorReqd = (bounds.top + bounds.bottotn)/2; 
for (int y = bounds.top: y i bounds-bottom: ++y) 

I 

int X ^ bounds.left: 
uehar mask; 

uchar *pb = _PbMaskForBitmapBlt(phitmapEdge. 
bounds.left* 


y, &mask): 

for { ; X < xMld: ) 


char b = *pb++: 
if (b = 0x00) 


I 

1 

mask = 0x80: 

1 

] 

// make sute the mask biimap ha^ been built 
BitMap ^pbitnmpMask; 
pbltmapHask = &prot->bitmapHask: 
if [pbitmapMask->baseAddr ^ NULL) 


X +- S: 
continue; 

j 

for £ : mask != 0: ++x. mask l) 

I 

if (b i mask) 

I 

if (x >= xMld) 
break: 
int idlr: 
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for (idir = 0; idir < DIM{s_adirLeft): -HHLdirJ 
[ 

strufit EIR dir “ e_adirLeft [idir]; 

1 f (_FP t InRe 0 1 (p puz - > bi ttnapMa s k. b oimd s * 

x+dx+dir-dx, 

y+dy+dir,dy} 

!_FGetBit (ppuz->bitMapMaiSk< x+dx+dlr. dx. 
y+dy+dir-dy) 

l_FGetlltSafe(‘'pbitmapMaak, x+dir.dxp 

y+di r. dy.) 

) 

I 

break; 

] 

1 

if [idir = DIM[s_adirLeft)) 

f 

// this pixel is an interior pixel 
if (ylnteriorLim < y) 

{ 

goto LRet ’ // we lose, there was a gap in the interior 
//edge pixels 

1 

ylnteriorLim = y+1; 

K = bounds. right; // force the V loop to terminate 
break; 

1 

else 


t 

break; 

1 

] 

if {idir = DIM(s^adirAbove)) 

( 

// this pixel is an interior pixel 
if [xlTiteriorLlni < x) 

goto LRet; // we Jose, there was a gap in the interior edge 
//pixels 

xltiteriorLim ^ x+l: 

y = bounds .bottom; // force the 'Y loop to terminate 
break; 

} 

else 

I 

// this pixel is not an interior pixel 
If (x < xInterlorReqd) 

goto LRet: // we didn’t find enough contiguous interior 
//edge pixels 

// we don’t mind that this edge pixel isn't an interior pixel, 

// and we can slop looking at tills scan line 
goto LPassedTop: 

1 

1 

I 


// this pixel is not an interior pbcel 
if (y < ylnteriorReqd] 

goto LRet: // we didn’t fmd enough contiguous interior 
//edge pixels 

// we don't mind tliat tliis edge phtcl isnl an interior pixeJ, 

// and we can stop looking at this scan line 
goto LPassedLeft: 

I 

J 

1 

mask = 0x80; 

I 

Assert [x >- xMid); 

// any pixels on Uie left half of this scan line are interior pixels 
if (ylnteriorLim < y] 

goto LRet; // we lose, there was a gap in the interior edge pixels 
ylnteriorLim = y+1; 

I 

) 

LPasaedLeft; 

// now scan top edge pixels looking for pixels that are interior to the proposed 
// asscmhled pieces in order to pa\s, there have to be interior edge pixels fn}m the 
// top of the piece down "mosr of tJic piece* witli no gaps. 

I 

int yMid = (bounds.top + bounds.bottom)/2; 
int xlnteriorLim = bounds*left; 

Int xInteriorReqd = (bounds * left + bounds * right)/2r 
for (int X = bounds*left: x < bounds.right: ++x) 

I 


Assert (y >= yMid); 

// any pixels on the top half tif this scan line are interior pixels 
if (xlnteriorLim ( x] 

goto LRet: // we lose* there was a gap in the interior edge pixels 
xlnteriorLim ^ x+1: 

I 

1 

LFassedTgp: 

fPassed = fTrue; 

LRet: 

return fPassed: 

1 

// write tmt the solved pu^/le state 

static int _FWrlteResult(PUZ 'ppuz. int iCase) 

// (miiited for bre vity 


_PlacePce 

// place the indicated piece into the puzzle at the specified offset 
// from its current posititm 

static void _PlacePce(PUZ *ppuz, int ipce* int Irot, int 
dxQffset. int dyOffset) 
i 

PCE *ppce - &ppuz-)pspce[ipce]; 

ROT *prot = &ppce■)arDt[irot] ; 

BitMap *^pbitmapMusk = &prot->bltmapHaek; 

Rect boundsSre = pbitmapHask-)bouiids; 

Rect boundsDst = boundsSre: 

_OffsotRectC&boundsDst. dxOffset, dyOffset); 


int y = hounds.top; 
uchar mask; 

uchar *pb = _PbM3skForBitmapBit(pbitmapEdge* x. y. 

&mask} ; 


for ( ; y < yMid: ++y* pb +- pbitmapEdge->rowBytes) 
[ 


if [*pb & mask) 

f 

int idir; 

for (idir = 0; idir < Dm(s_adirAbave] : ++idir) 


x+dx+dlr *dx, 


y+dlr,dy) 


struct DIR dir ^ s_adirAbove[idirl; 
if (_FPtInRect(ppuz'>bitmapMaEk.bounds, 

y+dy+dir.dy) 

i_FGetBitCppus->bitmapMask. xfdx+dir,dx. 
y+dy+dir.dy) 

&& I_FGetBltSafe(*pbitmapMask* x+dir*dx* 

) 


// record the bounds of whca‘ wc placed the most current piece 
ppuz-.>rectPrev " boundsDst; 
ppce-)icotUsed = irot; 

// copy the piece to the output image 

_TransferBitinapToImage(ppu 2 , prot, btMask. ppce->clr* 
dxOffset* dyOffset): 

// check to see if we' ve found the right edge yet 
if (ppuK->xRj ghtEdge — ppu 2 ->bits*dx 
prot->aedge[iedgeRight].fEdge) 

[ 

// test to see if the piece w e just put in is an edge piece, 

// wc require a more strict "edge" test for this purpose 
int y: 

int X = boundsSre.right - 1; 

for Cy = boundsSrc*top: y ( boundsSre^bottom; ++y) 
if {l_FGetBit(‘pbltmapMask. x, y)) 
break: 

if (y > (boundsSrc.top + 2*boundsSrc.bottom)/3) 

1 


\ 
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REALbasic® 


REAL Software and MacTech present the REALbasic Showcase to 
highlight some of the totastic solutions created by REALbasic users 
worldwide.The showcase illustrates the wide range of applications that 
developers using REALbasic can create. Some benefit any Mac user, and 
others are more specific.All of them are seriously cool! 

REALbasic is the powerful, easy-to-use tool for creating your own 
software for Macintosh, Mac OS X, and Windows. It runs natively on 
Mac OS X as well as earlier versions of the Mac OS. For more 
information, please visit: <www.realbasic.com>. 

The Made with REALbasic program is a cooperative effort between 
REALbasic users and REAL Software, Inc. to promote the products 
created using REALbasic and the people who create them. For more 
information about the Made with REALbasic program, please visit: 

<www.realbasic.com/realbasic/mwrb/Partners/MwRbProgram.html>. 
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Extend REALbasic with 
Advanced Plugins 

Spreadsheet Controls: 

We provide a wide range of spreadsheet controls for 
REALbasic, including multistyled and custom rendering 
spreadsheet controls. 
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Cryptography: 

We provide data encryption, encoding, 
compression and hashing for REALbasic. 

Supported Algorithms: 

• Encryption: 

- e-CryptIt 

- BlowFish {448 bit) 

-AES (Rijndael) (256 bit) 

• Encoding: 

- e-Cryptlt Flexible 
* Base 64 

- BinHex 

- MacBinary III 

- AppleSingle / Double 

- UUCoding 

• Compression: 

- Zip on Strings and streams (.gz) 

• Hashing and Checksums: 

-CRC32/Adler32 

- MD5/HMAC_MD6 
-SHA/SHA1 /HMAC SHA1 


other Plugins: 

We have many other 




plugins for REALbasic, 

Foot ► i 

including plugins to do 

Size ► 1 

advanced MacOS 




custom Controls. 


Speed up developement and make 
more advanced applications 
by using plugins ! Get free demos 
at www.einhugur.com 

Einhugur Software 
^ sales@einhugur,com 
www.einhugur.com 


db Reports 

Printing database driven 
reports from yq^r. REALbasic 
project has never befeii'^easier. 

Powerful expressions with 
easy-to-use interface make 
this an indispensable tool 
the REALbasic programi 
providing business solutfflhs. 




Download a free demo today. 

http://abDataTools.com 


Whistle Blower 

Enterprise server monitor and restart utility 
wh istleblo wer.sentnno n .com 


Connect to and validate the response from web servers, 
cgi scripts and over 23 other types of servers* 

Send email, pages and perform unattended restarts via 
MasterSwifch or PowerKey 

Shifts moke sure that the person on call when the server 
goes down is one who gets the page* 

68k, PPC and Corioon 

Web based administration lets you check on and restart 
your servers from anywhere. 

Customi 2 B your response to an outage with Apple Script 


email us at whistieblower@sentman.com 
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Picture 

Play 


Create digital image compositions on 
your Mac, quickly and easily. 



For more information, 
email chris@cre$cendosw.com, or 


visit us today at www.crescendosw.com! 


Corona 

PS 

accounting software 



“Easy to set up, eas} to use, 
and excellent support from 
the developer," 

Fim stars on VerswnTracker.com 
Four cows on Tucows.com 


• cash entry 
• invoicing 

• payroll 

• reports 


$64.95 


Version 1:9 now with: sales accounting 
entry" invoioes 
drag *n drop account 


Free 30-day trial 

http://homepage,mac,coni/idlewild/Coix>naUS,hqx 



A best friend for business! 

p*o, boK 472 * aurora • Oregon • 97002 
tdlewildp mac ,com 



• build both Macintosh and Windows screensavers 
with a single dick, no matter what system* you are using I 

• use any QuickTime 6.0 movie format: 

Macromedia Flash 5.0, MPEG, Cinepak, MP3, Midi, AVI, DV Video... 
or, now with version 3.0, build your own basic Slide Shows t 

• include a hidden movie that can be unlocked 
with a registration code 

• customize and fully-brand both Installers 
and Screensaver control panels with pictures and text 

• Screensavers install without DLLs, extensions, or restarts 


simple 

WYSIWYG 

ecT/tor 

supports 
interactive Flash 
and QuickTime 


consistent 
cross-platform 
user interface 


try before you buy 
fully functional 
oniine downloads 



creating screensavers 
for both Windows and Macintosh 
has never been this easy 
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LIGHTHOUSE 


the Time-Saving 
Triteriiet Assistant 


Spending long hours online searching for code snippets 
and developer docs? Get organized with Lighthouse. 





Store Account Info for access 
to membership sites & web mall 


Plugins Manager to add / edit 
Lighthouse piugins 


Web Favorites Organizer offers 
advanced bookmarking features 



Note Keeper saves code snippets, 
ideas, research notes, etc. 



Local Weather at your fingertips 
for home or travel 


Calendar & World Clock 

Personalized reference tools 



□ Bl^ 

□ ^ 
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for ( : y < bouitdsSrc.bottom: ++y) 
if (_FGetBit('pbitmapHaskt x. y)) 
break: 

if [y = boundsScc.bottom} 


i 


if ((ppuz ‘>c:pixelPuzzle % boundsDst, right) = 
&& Cppu2->cpc0 % (ppu2->lpceNe3£t+l)) = 0) 


>xRightEdge; 




ppuz’>xRightEdge = boundsDst.right: 
ppuz->yBottotiiEdge ^ ppuz->f:plxelPuzzle/ppiiz- 
e; 

ppuz->cpceRov = ppuz ■>ipceNe}n:H; 
ppuz->fChangedSize ^ fTriie: 


// if we hit the righi edge or hit n pixel in the lirst unsolved scan line* 

// update ppuz->yTopUnsolved 

if (ppu 2 ->rectPrev*right = ppuz->xRightEdge || 

boundsSrc*toptdyOffset “ ppuz >yToplinsolved) 


for ( 


++ppuz->yTopUnsolved) 


uchar maak: 

const uchar *pb = _PbMaskForBitiitapBlt {&ppuz- 
>bltinapMask> 

D, ppuz - >yTopUnsolved * ^niask) : 

Int x: 

foe [x = 0: X < ppuz->xRigbtEdge: x += 3, ++pb) 

I 

if {'pb OxFF) 
continue: 

for ( ; mask 1= 0: mask »= 1 * ++x) 
if (['pb & mask) =0) 
break; 

if [mask 1” D) 
break: 

I 

if (x < ppuz->xRlghtEdge} 
break: 


// update stats 
ppuz')cpixelEolved 


ppce->cpixel: 


// move the rotation we used to its correct Location for use later 
_0ffsetRect(&prot->blttnapMaskabounds, dxOffset* dyOffset); 
_0ffsetRect{&prot‘)bitiDapEdge.boundsp dxOffset» dyOffset); 


// update the piece amy 
if (ipce !™ ppuz->ipcaNext) 

( 

FCE pceT = ppuz->papce[ipce]: 

ppuzOpapce[lpce] = ppuz‘>papce [ppuz-)ipceMext] : 
ppuz->papce[ppuz->lpceNext] = pceT: 

I 

-H-ppuz‘>ipceNext; 

1 

// set the mask bitmap and color in the solved puzzle with the new piece 
static void _TransferBit]iiapTQliitage[PUZ ‘ppuz, const ROT 
*prot, 

BT bt. ushort clr, int dxOffset, lut dyOffset) 

// omitted for brevity 


// free the puzzle state and everything it allocated 
static void _FreePuz(PUZ *ppuz] 

f 

^FrcePuz 

1 

_FreeBits(&ppuz’>blts}: 

_F recBitmap(&ppuz->bitmapMask): 


if CppuzOpapce 3= NULL) 

1 


\ 

delete [] ppuz->pabBuffer: 
ppuz-)pabBuffer = NULL: 

ppuZ’>chBufferUsed = ppuz->cbBufferAlloc = 0 

, 

delete [] ppuz’>papce: 
ppuz->papce = NULL: 
ppuz->cpce = ppuz->ipceNext = 0: 

1 

1 


// free the buffer that holds the bitmap image data 
static void _FreeBiTs(BITS ‘pbits) 

1 

_FiecBits 

If (pbltB->pasw 1= NULL) 

1 


1 

delete [] pblts^^pasw: 
pbits-)pasw = NULL; 

] 

] 


_FCre3teBitmap 

// allocate a new bitmap with the specified bounding rea 

// if ppuz 1= NULL, use the prcallocted buffer, otherwise use new 

static int _FCreateBitinap(PUZ ‘ppuz, BitMap ‘pbltmap, int 
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xLeft. int yTop^ int xRiglit» Int yBottom) 

I 

_SetRect{ipbitmap-^boundfi. KLeft, yTop, xRight. yBattom); 
pbitiiiap->rowByteE = (((xHight - xLeft) + 15) >> 4) << 1; 
long cbBitmap = _CbBitinap (’pbitniap); 

if (ppu2 !- NULL) 

I 

// grab the chunk we need 

pbitniap->baseAddi: ^ ^ppU 2 ->pabBuffer [ppuz->c'blufferUsed] : 
ppuz->cbBufferUsed += cbbitraap: 

1 

else 

t 

pbitmBp->baseAddr = new charIcbBitiiiapJ: 
meraset Cpbitiiiap->baEeAddr * 0. cbBitmap) ; 
return pbitmap->baseAddr != NULL: 

\ 


^FreeBilmap 

// free a bitmap whose bits were individually allocated 

// be eatrfuhniost bit maps get aUocated from the preallocated buffer 

static void. _FreeEitiiiap(BitHap *pbitmap) 

[ 

if (pbitTiiap->basGAddr 1= NULL) 

[ 

delete [] pbitiiiap‘>haseAddc: 
pbitEnap->baseArfdr = NULL: 

I 


_FGetflii 

// return the state of the specified bit 

static. Int _FGetBlt(const BitMap ^bitmap, int x, int y) 

1 

ucbar raask; 

uchar ‘pb =" _PbMaEkForBiti!iapBit (^bitmap, x, y, &niask): 

int fSet ^ (C*pbJ & mask) != 0; 
return fSet; 


_FGetBitf>afe 

// return the value of Uie specified hit if it's withing the bitmap, 

// otherwise return 0 

static int FGetBitSafe(const BitNap ^bitmap, int int y) 

1 

Int fSet = _FPtInRect(bitmapabounds♦ x* y) ? 

_FGetBit{bitmap, x. y) : D: 

return fSet: 

I 


_SetBit 

// makes sure the indicated bit is set returns non zero if the bit needed to be set 
static void _SetBit(BitMap ^pbitmap, int x, int y) 

[ 

uchar mask; 

uchar *pb = _PhHaskFarBitniapBit (pbltmap. x. y, tiinask) : 

*pb 1= mask: 


// set a hit in the specified bitmap 

static void _SetBit(BitMap 'pbitmap, int x, int y, int fSetJ 

1 

uchar mask: 

uchar *pb = _PbMaskForBit[iiapBit (phitmap, x, y. &mask) : 

if (fSet) 

'pb 1“ mask: 
else 

•pb ^ask: 


_CbBitmap 

// return size needed for the specified bitmap's bitmap data 
static long _GbBitmap(const BitMap &bitmap) 

[ 

return [bitmap.bounds.bottom - bitmap abounds,top) * 
bitmap^rowBytes: 


1 


_PbMiiskForBitmapBit 

// for the specified pixel bxiaiiofi within the bitmap, reaim the pointer 

// to the correct byte in tlie bitmap data and the mask for the specified bit 

// note - this is done mcrcmentaily in time critical routines 

static uchar *_PbMaskForBitmapBlt(const BitMap Vpbitmap* int 

X, int y. uchar ^pmask) 

y -= pbitmap->bounds.top: 

X -= pbltmap‘■>bounds.left; 

^pitiask = OxSO » (x & 0x7): 

return [uchar •}&pbitmap->baseAddr[y * pbltmap->rowBytea + 

(x»3)]: 

1 


JfffeetPi 

// offeei the pohit by the specified amounts 

static void _0ffsetPt(PT *ppt, Int dx, int dyj 

I 

ppt->x += dx: 
ppt->y dy; 

] 


_FPtInfiect 

// LS the specified point in the specified rect? 

static int _FPtlnRect[const Rect direct, int x, int y) 

I 

return rect. left x x < rect.tight 

rect.top <= y y < met .bottom: 


_SctReci 

// like QD routine, but thread safe 

static void _SetRect{Rent ‘prect, short left, short top. 
short right, short bottom) 

[ 

prGet->left = left* 
prect->top = top: 
prect->right = right: 
prect->bottoni = bottom: 


_OffisetRect 

// like QD routine, but thread safe 

static void _OffBetRect[Rect 'prset, short dx, short dy) 
f 

prect‘)left += dx: 
prect-bright +” dx: 
prect->top += dy: 
prect-^bottom += dy: 

[ 


_ExpandRect 

// expand the specified rect to include the specified .scan tine 

static void _ExpandRect(Rect 'prect, int y, int xFirst. int 

xLim) 

I 

p rect->bottom = y 1: 
if {precr->left > xFirst) 
prect >left = xFlrSt: 
if (prect-bright < xLlm) 
prect->right = xLim: 


// find all of the pixels in the original puzzle image data which match Lhe 
// specified "color' , constraining the search to the specified rectangle 
static long _GolorFill[BITS 'pbits, const Rect ireetBounds, 
ushort clrMatch, BitMap ‘pbitmapMask} 

1 

ushort *psw = &pbits-)pasw[rectBounds.top * pbits->dx + 
reetBounds.left] : 

int cswSkip = pbits->dx - (reetBounds.right - 
rectBoimds,left): 

long cpixelMatch “ D: 

for [int y - reetBounds.top: y i reetBounds.bottom: ++y) 

t 

for [int X “ rectBounds.left: x < reetBounds.right: 

■H-x. t+psw) 

f 

If (*p3w = clrMatch] 
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*psw - 0: 

_SetBit(pbitmapMask. x, y): 

■H-cpixelMatch; 

I 

I 

paw += cEVfSkip: 

I 

return rpixelMatch; 

f 

_HiiilUEdj'cBilniap 

// find the Ixjimdar)' of jl piece and consima a bitmap with tho,se bits set 

static void ^BuildEdgeBitmap(const BitMap SibitmapMask* BltMap 

*pbitinapEdge) 

t 

for (int y = bitmapMask,bounds.top^ 

y < bitmapMask.bounds.bottom; -H-y) 
f 

for (int X = bltmapHask.bounds.left; 

H < bicmapMask.bounds.right; ++x} 

( 

if (_FGetBit(bitmapHask. x. y)) 

[ 

for (int idir = 0; idir < DIMts^adirEdge); -H-idic) 

I 

const struct DIR ^pdir ” 6iS_adirEdge[Idir] ; 

if (]_FGetEitSafe[bltiiiapMask, x+pdlr->dx. y+pdir- 

>dy)) 

[ 

_SetBlt(pbitmapEdge, x, y): 
break; 

I 

J 

J 


_pRoiaic Bitmap 

// rotate the given bitmap by the specified miml>er of quarter turns and put 
// the result in a newly allot^ated bitmap 

static Int _FRotateEitmap{PUZ *ppU 2 , const BitMap febitmapSrCt 
int itot. BitMap ^pbitmapDst) 

I 

Rect rectBounds - bitTnapSrc .bounds; 

switch (itot) 

1 

case 1: 

if [ !_RCreateBttEasp (ppux. phitmapDst, rectBounds . top, 


rectBounds. left. rectBounds.bottotit, 
rectBounds.right)) 

return fFalse; 

_RotateBit!nap90 (bitmapSrc pbittnapEst) : 
break; 
case 2: 

if ([_FCreateBitinap tppuz , pbitmapDst, rectBounds . left, 
rectBoutids. top, rectBounds. right + 
rectBounds.bottom)) 

return fFalse; 

_RotateBitmaplSO(bittnapSrc . pbitmapBst); 
break; 
case 3; 

if ( f_FCreateBitn3ap fppuz . pbitmapDst, rectBounds . top. 
rectBounds.left. rectBounds.bottom. 
rectBounds.right)) 

return fFalse; 

_RotateBitinap270 (bitmapSrc , pbitmapDst} ; 
break: 

I 

return fTrue: 

_Rf>tateBitmap180 

// rotate the source bitmap by 1^0 dej^cs into the destination bitmap 
static void _RotateBitniapl80 (const BitMap SbitinapLSrc. 

BitMap *pbitinapDst) 

for (int ySrc = bitmapSrc.bounds.top. 

yDst = pbitmapDst' 

>bouiids.bottoiti-l; 

ySrc < bitmapSrc.bounds.bottom; 

+H-ySrc, - ^yDst) 

for (int xSrc ^ bitmapSrcAbounds.left» 

xDst = pbitraapDst->bounds.right-1: 
xSrc < bitmapSrc.bounds,right; 

++xSrc. ■'xDst) 

_SetBit[pbitmapDstt xDst. yDst. _FGetBit[bitmapSrc. 
xSrc, ySrc)); 


/J _RotateBitmap9D und _RotateBitmap27D cimittcd for brevity 

_fktHdgeInJo 

// get info :ibout the edge;; of the specified piece 

static void _GetEdgeInfo{PUZ *ppu 2 . PCE *ppce) 

I 

ROT ^prot = &ppce->arot [0]; 

BitMap ‘pbitmap - &prot-)bitmapEdge: 

Rect bounds ” phitmap-)bounds; 




earr. 



cCtj 

B'LeeP. 

Bia 


nero 

Learn 

rano h 

Coooa^ 

Intensive Classes for Programmers 

WWW. big^ner drarick.com 


404.210.S663 


August 2002 • MacTech 


83 






ppce-^cEdgeSide = 0; 

for (int idlr = 0; idir < DIM(s_adirEdge) : -H-idir) 
f 

const DIR dir = s_adirEdge[idir] ; 
int z, y: 

int ^First^ ^Lim, *p 2 ; 

if (dir.dx 1= 0) 

I 

pz = ^x; 

zFirst - bounds,left: 
zLim = bounds.right; 

y = dir.dx > D ? bounds.top : bounds,bottoin - 1: 

) 

else 

( 

pz - £iy: 

zFirst = bounds.top: 
zLira = bounds.bottom: 

X = dir.dy >07 hounds.left : bounds,right ‘ 1: 


// scarj to sec If this side lcH:iks like m edge piece 
EDGE *pedge = £iprot - )aedge [idir] : 
pedge'>fEdge = fFalse: 
int dzEdge - zLim - zFirst; 
if (dzEdge < 0) 
dzEdge ’ -dzEdge; 

int cplxEdge “ 0: 

for f*pz = zFirst : 'pz zLim: 'pz 1] 
! 

if (i_FGetEit('pbitmap, x, y)) 

I 

CplxEdge = 0: 
continue: 

1 

if [cpixEdge++ ) 0) 

1 

if (cpixEdge — dzEdge/2) 

prot->aedge[idir].fEdge “ fTrue: 

I 

else if {prot->aodge[idir],fEdge] 

[ 

prot■>aedge[idir],fEdge = fFalse; 
break: 

I 

[ 

if (prot->aedgG[idir].fEdge) 

-H-ppes->cEdgeSide; 


// copy the edge infonnation to the other rotations 
for (int irot = 1: irot < DIH(ppce->arotJ : ++irot) 
for (int ledge ” Oj iedge i 4; ++iedge) 
ppce->arot[Irot].aedge[iedge] — 

prot->aedgeI(ledge + irot) % 4]; 


_findC Corners 

// find a reasonable guess for the corners of the piece stored in the bitmap 
static void _FindCorners(const BitMap fiebitmap, 

FT 'pptTop, FT *pptBottom) 

I 

Rect reetBounds - bitmap.bounds: 
pptTop->x - -1; 

for (int d “ D; pptTop->x = -1; ++d) 

r 

FT pt; 

for (pt.x ” rectlounds■right'1, pt.y “ reetBounds.top+d; 
pt.y < reetBounds.bottom pt.x >= reetBounds.left: 
--pt.x. -t+pt.y) 

( 

if (_FGetBit(bitmap, pt.x. pt.y)) 

I 

pptTop->x = _XFirstBit [bitmap. ppt.Top->y = -H-pt,y); 
break: 

[ 

I 


1 

pptBcittom->x = -1: 

for (int d = D: pptEottoni'>x == *l:HH-d) 

I 

PT pt: 

for [pt.x = reetBounds.right-1, pt.y = 
reetBounds.bottom^1-d; 

pt.y >= reetBounds,top && pt.x reetBounds,left: 

--pt.x, --pt.y) 

( 

if (_FGetBit(bitmap, pt.x. pt.y)) 

I 

pptBottom->x = _XFirstBit(bitmap, ppiBottom->y = -■ 

pt.y): 

break; 

1 

[ 

) 

] 


_CptGeTEdgeShape 

// reairn up lo three "interesting'* points along the right edge of the piece 
// stored in bhniitp 

static int _CptGetEdgeShape(const BitMap ^bitmap. 

PT paptCheck[3l) 

[ 

// fjnstj find the comers, more or less 
FT ptCornerTop. ptCornerBottom: 

„FlndCorners(bitmap, ^ptCornerTop, ^ptCornerBottom): 
int dyQuarterEdge “ (ptCornerBottom.y - ptCornerTop.y)/4: 

int cptCheck = 0: 

Rect reetBounds = bitmap.bounds; 

PT ptln “ [xNil, zNllI, ptOut = (zNil. zNilf: 

int iptln - -1, iptOut = -1; 

int xin “ reetBounds.right, xOut " reetBounds.left-l: 

Int fOutPrev = fFalse, flnPrev = fFalse: 

Int yMidMin = ptCornerTop.y-i-l: 
int yMidLim = ptCornerBottom,y: 

PT aptJump[255]: 
int eptJump - 0: 

PT ptPrev; 

ptPrev.x = _XFirstBit[bitmap, ptPrev.y = yHidMin); 

apt Jump [eptJump-H-] = ptPrav: 

for (PT ptCur - ptPrev; -•-•‘ptCur,y < yMidLim: ) 

I 

ptCur.x " _XFirstBlt(bitmap, ptCur.y): 

if (ptCur.x ptPrev.x) 
continue: 

int dx = ptCur.x - ptPrev.x: 
int fin = dx ( 0; 
int fOut = tfin: 

int yPeak: 

if (fOut fInPrevJ 
[ 

// we Itivc k)cal mini 

if (ptPrev.x C zin 

iiii _FMlddleish(ptFrev.y. ptCur.y. yHidMin, yMidLim. 

6i.yFeak} 

) 

( 

ptin.x = ptPrev.x: 
ptin.y = yPeak; 
xIn = ptPrev.x; 
iptln = cptJump-l: 

1 

I 

else if [fin fOutPrev) 

I 

// we have a local max! 
if (ptPrev.x > xOut 

_FMiddlelsh[ptPrev,y. ptCur.y, yMidMin. yMidLim, 

5!yPeak) 

) 

1 

ptOut.x = ptPrev.x; 
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ptOut,y = yPeak: 
xOut = ptPrev.x: 
IptOut = cptJump-1; 


The #1 Relational Database on Mac OS X 


\ 

aptJump[cptJump++] = ptCur: 
ptPrev = ptCur: 
fInPrev tin; 
fOutPrev ” fOut: 


if (ptln,x ]- zNil) 

[ 

Int IptPrev, IptHext, d.x: 

fgr (IptPrev = iptln; ; ) 

I 

if {--iptPrev < OJ 
goto LCheckout; 

dx “ aptJump[iptPrev+1].X - aptJump[iptPrevj ,x: 
if (dx < -1) 
break; 
if (dx > 0) 

if (dx ) 1 II aptJump[iptPtev+1].X ) ptIn.x+1) 
goto LCheckOut: 

) 

for [iptNext “ iptln; ; ) 

[ 

if (f+iptNext >= cptJump) 
goto LCheokOut; 

dx = aptJump[iptNexti .X - aptJump [iptNext-1].x; 
if (dx > IJ 
break; 
if (dx < D) 

if (dx < -1 II aptJump[iptNext].X < ptln-x-i) 
goto LCheckOut; 

] 

// there hail to he jicimc bump to qLialifv as an innie 
if (aptJump [IptNext] .y ‘ (aptJumpUptPrev+1]-y^l) > 
dyQuarterEdge*2) 

goto LSmooth; 

paptCheck[cptCheck]rx * aptJump [iptPiev],x; 
paptCheck [cptCheck+f) .y ^ aptJump [lptPrev+1] .yl: 
paptCheck [cptCheck++] - ptin; 
paptCheck [cptCheck+f] “ aptJuntp [iptNext] ; 
goto List; 


LChetkOut: 

if (ptOutnX J= zNil && {ptln*x = tNil | | 
ptOutnX ““ reetBounds* right*1)) 
f 

int iptPrev. iptNext^ dx; 

for (iptPrev = iptOut: ; ) 

I 

if [--iptPrev < 0) 
goto LSmooth: 

dx = aptJump [iptPrev+l].X ■ aptJump [iptPrev].x; 
if (dx > 1) 
break: 
if (dx < 0) 

if [dx < -1 I I aptJump [iptPray-i-l] .X < ptOut.x-1) 
goto LSmooth: 

] 

for (iptNext ^ iptOut; : ) 

( 

if (-l-t-iptNext >= cptJump] 
goto LSmooth; 

dx = aptJump [IptNext].X - aptJump[IptNext-ll.x: 
if (dx < -1) 
break: 
if (dx ) 0) 

if (dx I I I aptJump[iptNext] .x > ptOut.x-i-1) 
goto LSmooth; 


// there ha.s to be some bump to qualify as an outie 

if (aptJump[iptNext].y - (aptJump [iptPrev+l].y-1) ^ 
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dyQuarterEdge*2) 
goto LSmooth: 

paptChecik[cptCheck] .X = aptJuinpIlptFrev] .x: 
paptGheokfcptCheck++]-y = aptJuiiip[iptPrev-i-l] .y-1: 
paptChecktcptCheck++] = ptOut: 
paptCheck [cptCheck+t] = aptJump[iptNext]; 
goto LRet: 


LSmooth; 

if (ptln^x = sNil && ptOut.x == aNil) 

I 

int yWant = ptCornerTop.7 + dyQuartetEdge; 
int ipt = 1: 

while [ipt < cptJump aptJump[ipt] ,y <= yWaut) 
-H-ipt; 

paptClietk[optCheok] .y = yWant e 
paptCheck[cptCheck-H-] .x = aptJurap [ipt-L] 

yWant = ptCornerlottom.y - dyQuarterEdge; 

ipt = cptJurap-l: 

while (aptJump[ipt] .y ) yWant) 

• ’ipt: 

paptCheck(cptCheck]*y = yWant: 
paptCheckicptCheck+t]/x = aptJump[ipt],x: 

1 

else 

[ 

if (ptin.x zNil) 

paptCheck[cptCheck-i"t] ^ ptln; 
if (ptOut.x 1= aWilj 

paptCheck [cptCheck4+] = ptOut; 


LRet: 

return tptCheck: 


yy determine if any element of the ^ment [xi.x2) is within the 
yy the range [xFirst, xLim). If noi. return fFalse, If so, 

// set *pxMid to a pixel inside the both ranges, as near the raidpint of 
yy [xFirst, xLira) as possible 

static int _FMiddleish(int xl. int x2, int xFirst. int xLira, 
int *px^id) 

I 

yy calculate the midpoint and then tlie limits of the center segment 
int xMid = (xFirat + xLi!n)/2: 

If [x2 <= xFirst || xLim <= xl) 
return fFalse: 

if (xl <= xMid xMid < x2) 

*pxHid = xMid; 
else if (xl > xMld] 

^pxMid = xl; 

* pxHid ° x2"I; 
return fTrue; 


yy find the rightmost set bit in tlie specified row of the bitmap 
static int _XFirstBit (const BitMap &biitnap, int y) 

I 

int x; 

for (x = bitmap abounds.right-i ; x y- bitmap,bounds,left e -- 

x) 

if {_FGetBlt(bitmap, x. y)J 
break; 
return xe 
I 

yy MusecFmmTime omiited for brevity 
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We^re true insiders. 


O’Reilly and Apple have joined forces to bring you unparalleled 
access to the experts developing OS X. Get on the Inside track 
(and stay there) with our OS X books and the O’Reilly Networks 
Mac DevCenter at www.oreillynet.com/niac. 


We keep pace with Java. 

Our Java books — and our online site for 
Java developers, on,java,coni—offer the most 
comprehensive and up-to-date information 
available to help you keep pace, too. 


We know Unix— 
inside and out. 

We cut our teeth on Unix: O’Reilly has 
been publishing the most respected and useful 
books on Unix for well over a decade, 
and we re still at the head of the pack. 


JAVA 


Cocoa 


A ITK-a 

of-OHjelHy ftftsHXBJtWtlSc AJI mhw tradwwrks ars (he prap^ 

ctf ihrir rtipKtlvt dwtirtt. 


WWW.OREILLY.COM • 800-998-9938 
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WNJi rival SCM systems^ tfie only way to 
quicken the pace is to cut corncfs < but in the 
long run you pay the price with missed 
deadlines^ uncertain contents, buggy releases 
and no way back to previous builds. 

With Perforce^ the fast way is always the 
right way. Install it fastp team it fast, execute 
operations fast. With other SCM systems, 
developers face an unpleasant choice: 
do it the right way or do tt the fast way. 

Perforce's speed and reliafalfity mean fast is right. 
See how Perforce compares with other 
leading SCM systems at 
http://www.perfo rce.co m/perfo rce/ reviews ,htm I 


Run at full speed even with hundreds of users 
and millions of hies. At the core of Perforce lies 
a relational database with well-keyed tables, 
so simple operations can be accomplished in 
near- 2 ero time. Larger operations Hike labeling 
a release and branching) are translated into 
keyed data access, giving Perforce the scalability 
that big projects require. 

Work anywhere. Perforce is efficient over high- 
latency networks such as WANs, the Internet and 
even low-speed dial-up connections. Requiring 
only TCP/IP, Perforce makes use of a well-tuned 
streaming message protocol for synchronizing 
client workspace with server repository contents. 


Develop and maintain multiple codelines. 
Perforce Inter-Rle Sranching™lets you merge 
new features and apply fixes between codelines. 
Smart metadata keeps track of your evolving 
projects even while they develop in parallel. 

Truly cross platform. Perforce runs on more than 
50 operating systems, including Windows and 
nearly every UNIX variation, from Linux and 
Mac OS X to AS400 and more, 

integrate with leading IDEs and defect trackers: 
Visual Studio,NET*, Visual C++’", Visual Basic-, 
JBuilder^ CodeWarrior% TeamT^ack^ Bugzilta’"', 
Control Center-, DevTrack’ packages, and more. 


PEReD«€E 

SOFTWARE 

Fast Software Configuration Management www.pefforce.com 


Download your free 2-u5er, non-expiring, full-featured copy now from www.perforce.com 
Free (and friendly) technical support is on hand to answer any and all evaluation questions. 


All Iradsmarte viBod tisiein am either iKe [radantarfes or imglEtwed Iradsmarfcs of their owher?. 
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We're Easier. 

Create anything from prototypes to full professional applications. Just drag and drop interface 
elements while REALbasic handles the details. You concentrate on what makes your stuff great — 
your ideas! REALbasic creates native compiled applications for Macintosh, Mac OS X and Windows 
without platform-specific adjustments, ft's the powerful, easy-to-use tool for creating your own 
software. Each version of your software looks and works just as it should in each environment. 

Complex problems shouldn't require complex solutions. The answer is REALbasic. 



REALbasic4.5 


NEW VERSION 


Come see us at Macworld in MacTech Central! Download a free demo* www.realbask^com 












